https://github.com/jonhadfield/gosn-v2
https://github.com/jonhadfield/gosn-v2
Last synced: 3 months ago
JSON representation
- Host: GitHub
- URL: https://github.com/jonhadfield/gosn-v2
- Owner: jonhadfield
- License: mit
- Created: 2019-12-30T15:15:23.000Z (over 6 years ago)
- Default Branch: master
- Last Pushed: 2026-01-29T18:53:55.000Z (5 months ago)
- Last Synced: 2026-01-30T07:20:52.722Z (5 months ago)
- Language: Go
- Size: 3.51 MB
- Stars: 17
- Watchers: 1
- Forks: 6
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Agents: AGENTS.md
Awesome Lists containing this project
- awesome-standard-notes - gosn-v2 - A library written in Go (Libraries / Importers, Exporters, and Converters)
README
# gosn-v2
[](https://www.travis-ci.org/jonhadfield/gosn-v2) [](https://circleci.com/gh/jonhadfield/gosn-v2/tree/master) [](https://godoc.org/github.com/jonhadfield/gosn-v2/) [](https://goreportcard.com/report/github.com/jonhadfield/gosn-v2)
`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
```bash
GO111MODULE=on go get github.com/jonhadfield/gosn-v2
```
## Quick Start
```go
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):
```bash
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](https://pkg.go.dev/github.com/jonhadfield/gosn-v2).
- For issues or feature requests, open a GitHub issue with reproduction steps or context about your Standard Notes setup.
## Contributing
Review the [Repository Guidelines](AGENTS.md) 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](LICENSE).