protocol

package
v0.1.1 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Sep 30, 2026 License: Apache-2.0 Imports: 19 Imported by: 0

Documentation

Overview

Package protocol implements the server side of the sqlite-remote protocol over WebSocket. The message types in internal/gen are generated from proto/sqlite_remote/v1/sqlite_remote.proto. proto/ is a copy of the definition in sqlite-remote-vfs and is updated with scripts/sync-proto.sh.

Index

Constants

View Source
const Path = "/v1/ws"

Path is the WebSocket endpoint. It is the only path the ingress exposes publicly.

View Source
const Version = 1

Version is the protocol version of this server.

Variables

This section is empty.

Functions

This section is empty.

Types

type Options

type Options struct {
	Store store.Store
	Log   *slog.Logger
	// MaxFrameBytes limits the size of every frame in both directions.
	MaxFrameBytes uint32
	// PingInterval is the ping interval sent to clients. A connection without a frame for three intervals is
	// closed.
	PingInterval time.Duration
	LeaseTTL     time.Duration
	// MaxCommitBytes limits the total block data of one commit across all its parts.
	MaxCommitBytes uint64
	// HelloTimeout is the time a new connection has to send its Hello.
	HelloTimeout time.Duration
	// AllowedOrigins lists the hosts from which a browser page may connect. In each pattern, `*` matches any part
	// of a host, e.g. `*.example.com` or `127.0.0.1:*`. Empty means same origin only. Clients other than browsers
	// send no Origin header and are not affected.
	AllowedOrigins []string
	// ServerID is the public address of this server, e.g. "wss://vfs.example/v1/ws". It is part of the transcript a
	// client signs at login. If it is empty, every login is rejected.
	ServerID string
	// ChallengeTTL is how long a challenge is valid. Zero means 30 s.
	ChallengeTTL time.Duration
	// Tokens, if set, admits only clients with a valid access token bound to their key. After the token has expired,
	// plus the verifier's leeway, the connection is closed at the next frame other than a Ping. Pings keep the
	// leases renewed until the client reconnects with a new token.
	Tokens *token.Verifier
	// Now returns the current time. Nil means time.Now.
	Now func() time.Time
}

Options configures a Server.

type Server

type Server struct {
	// contains filtered or unexported fields
}

Server serves the protocol on WebSocket connections. A client logs in by signing a challenge with its private key. The server derives the client's subject from the public key.

func NewServer

func NewServer(opts Options) *Server

NewServer returns a Server for opts.

func (*Server) ServeHTTP

func (s *Server) ServeHTTP(w http.ResponseWriter, r *http.Request)

ServeHTTP upgrades the request to a WebSocket and serves it until the connection ends.

func (*Server) Shutdown

func (s *Server) Shutdown(ctx context.Context) error

Shutdown closes every connection with StatusGoingAway and waits until all connections have ended or ctx is done. Clients reconnect, possibly to another server instance, and resume their leases there.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL