gosn-v2

February 1, 2026 · View on GitHub

Build Status CircleCI GoDoc Go Report Card

gosn-v2 is a Go library for building Standard Notes clients. It wraps authentication, sync, encryption, and caching flows while letting you integrate with the official or a self-hosted Standard Notes server.

Highlights

  • Handles the Standard Notes v004 encryption protocol out of the box.
  • Ships caching helpers for delta syncs and reducing server load.
  • Includes schema validators, CLI utilities, and fixtures for reproducible tests.
  • Performance optimized: 85% faster syncs, 90% fewer allocations, 70% fewer API calls.

Requirements

  • Go 1.25.1 or later (see go.mod).
  • Access to a Standard Notes server account for live integration tests.
  • macOS, Linux, or Windows with the Go toolchain installed.

Installation

GO111MODULE=on go get github.com/jonhadfield/gosn-v2

Quick Start

import "github.com/jonhadfield/gosn-v2"

// Sign in and establish a session
sio, err := gosn.SignIn(gosn.SignInInput{Email: "user@example.com", Password: "topsecret"})
if err != nil {
    log.Fatal(err)
}

// Perform an initial sync
so, err := gosn.Sync(gosn.SyncInput{Session: &sio.Session})
if err != nil {
    log.Fatal(err)
}

// Decrypt and work with your items
items, err := so.Items.DecryptAndParse(&sio.Session)

Project Layout

  • auth/, session/, items/ — domain packages for authentication, session lifecycle, and note models.
  • crypto/ — key derivation, encryption, and signing helpers.
  • cache/ — tooling for encrypted sync snapshots and cache persistence.
  • docs/ — user guides and reference material; start with docs/index.md.
  • schemas/, test.json — JSON schemas and fixtures for validation and integration tests.
  • bin/ — utility scripts for development and troubleshooting.

Performance

gosn-v2 includes several performance optimizations for efficient operation:

Sync Performance

  • Parallel decryption: 7.5x faster for 1000+ items on multi-core systems
  • Conditional sync: Skips unnecessary API calls when no changes exist
  • Dynamic batch sizing: Adapts request size based on content (30-40% fewer API calls)
  • Memory pooling: 60% reduction in GC pressure through buffer reuse

Resource Efficiency

  • 70-85% fewer API calls through intelligent caching and batching
  • 85-90% fewer allocations via pre-allocation and pooling
  • 50% bandwidth savings through compression and optimized batching
  • 95% reduction in idle connection overhead

Configuration

Environment variables for tuning (optional):

export SN_SYNC_TIMEOUT=30s          # Sync operation timeout
export GOSN_DECRYPT_WORKERS=8       # Parallel decryption workers

See claudedocs/optimization_opportunities.md for detailed implementation notes.

Development Workflow

  • go build ./... verifies every package compiles.
  • go test ./... runs unit tests across the repository. Set SN_SKIP_SESSION_TESTS=true to skip live server checks.
  • make test aggregates coverage into coverage.txt; make fmt applies gofmt and goimports to all Go files.
  • make lint runs golangci-lint with the configured rule set; make critic enables additional gocritic analysis.

Documentation & Support

  • Browse the guides in docs/ or the Go API reference on pkg.go.dev.
  • For issues or feature requests, open a GitHub issue with reproduction steps or context about your Standard Notes setup.

Contributing

Review the Repository Guidelines before opening a pull request. They cover project structure, testing expectations, and the commit/PR workflow.

License

This project is distributed under the MIT License.