tether

package module
v1.4.0 Latest Latest
Warning

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

Go to latest
Published: Oct 9, 2026 License: Apache-2.0 Imports: 32 Imported by: 0

README

Tether

Tether is a reactive backend framework for Go. Write your queries and mutations as plain Go functions, and Tether keeps every connected client in sync with your database in real time. You don't write WebSocket code, cache invalidation logic, or pub/sub plumbing.

Read the docs →

go get github.com/recodeorg/tether

Why Tether?

Reactive by default

In Tether, every query is live. When a client subscribes to a query, Tether records which rows and collections the query read. When a mutation changes any of that data, Tether reruns the affected queries and pushes the new results to every subscribed client. You don't opt in and you don't wire up events; it's how the framework works.

Identical subscriptions are batched automatically. If a thousand clients are watching the same chat room, the query runs once and the result is fanned out to all of them.

Secure by design

Tether assumes your code will eventually make a mistake, so its defaults are safe:

  • Guards are reusable, reactive authorization checks. You write "can this user see this room?" once and call it from any query. Guards are cached per user and re-evaluated automatically when the data behind them changes, so revoking access takes effect immediately on every open subscription. Clients who pass the same guard with the same result still share one batched query execution, so you get per-user authorization without per-user query cost.
  • Queries and guards are read-only. Any attempt to write to the database from a query or guard is rejected at the connection level.
  • Internal functions stay internal. Pass Internal() when registering a query or mutation and clients cannot call it. An internal mutation can still be run from your server code, such as a scheduled task.
  • Hardened defaults include WebSocket message and subscription limits, origin checks, redaction of auth tokens from logs and metrics, and path-traversal and content-sniffing protection for file storage.
Scales horizontally with no extra code

Swap SQLite for PostgreSQL and you can run as many Tether instances as you like behind a load balancer. Instances coordinate through Postgres, so a mutation on one server updates clients connected to any other server, and scheduled tasks run exactly once across the cluster. There's no Redis, message broker, or extra configuration.

Batteries included
  • Authentication: bring your own tokens (JWTs, session tokens, and so on) by implementing a single VerifyToken method, or use the included Clerk and OpenID Connect adapters.
  • HTTP actions: handle webhooks and other HTTP endpoints with the same auth, guards, storage, and scheduler as a mutation.
  • File storage: signed upload and download URLs, server-side uploads, optional public file URLs, and server-side commit hooks, with included local disk and S3-compatible adapters.
  • Scheduling: run mutations after a delay or on a cron schedule. Tasks persist across restarts.
  • Transactions: writes inside a database transaction only notify clients once the transaction commits. Rolled-back writes never reach clients.
  • Profiling: built-in performance profiling for queries, mutations, guards, and database calls.
  • Client libraries: first-class TypeScript and React clients.

Philosophy

Tether is built around a few principles:

  • Radical simplicity. The public API should stay small and obvious. If a feature needs a lot of explanation, it probably doesn't belong in Tether.
  • Effortless infrastructure changes. Switching from SQLite to PostgreSQL, or from local disk to S3, should be a one-line change.
  • No vendor lock-in. Tether always runs as a single, self-contained Go binary on any server you control.
  • Pluggable, not hard-coded. Features that depend on outside infrastructure, like storage, come in through adapters instead of being baked into the core.

See CONTRIBUTING.md for more on how these principles guide the project.

A quick look

A chat room where only members can read messages, and new messages appear for everyone instantly:

type Message struct {
	ID     uint `gorm:"primaryKey"`
	Body   string
	RoomID string `tether:"track"`
}

type RoomMember struct {
	UserID string `gorm:"primaryKey"`
	RoomID string `gorm:"primaryKey"`
}

func main() {
	db, err := gorm.Open(sqlite.Open("app.db"), &gorm.Config{})
	if err != nil {
		log.Fatal(err)
	}

	engine, err := tether.NewEngine(db)
	if err != nil {
		log.Fatal(err)
	}
	defer engine.Close()
	engine.CreateTable(&Message{})
	engine.CreateTable(&RoomMember{})

	// A reusable authorization check. Its result is cached per user and
	// re-evaluated automatically when room membership changes.
	engine.RegisterGuard("isMember", func(ctx *tether.GuardCtx) (any, error) {
		userID, err := ctx.Auth.GetIdentity()
		if err != nil {
			return false, nil
		}
		ctx.TrackCollection("room_members", "user_id", userID)

		var member RoomMember
		err = ctx.DB.Where("user_id = ? AND room_id = ?", userID, ctx.Params["room"]).First(&member).Error
		return err == nil, nil
	})

	// A live query. Subscribers get a fresh result whenever the messages
	// in this room change.
	engine.RegisterQuery("getMessages", func(ctx *tether.QueryCtx) (any, error) {
		room := ctx.Params["room"].(string)
		allowed, err := ctx.Auth.ExecuteGuard("isMember", map[string]interface{}{"room": room})
		if err != nil || allowed != true {
			return nil, errors.New("forbidden")
		}

		ctx.TrackCollection("messages", "room_id", room)
		var messages []Message
		ctx.DB.Where("room_id = ?", room).Find(&messages)
		return messages, nil
	})

	// Mutations don't need to notify anyone. Tether sees the write and
	// updates every affected query on its own.
	engine.RegisterMutation("sendMessage", func(ctx *tether.MutationCtx) (any, error) {
		message := Message{
			Body:   ctx.Params["body"].(string),
			RoomID: ctx.Params["room"].(string),
		}
		if err := ctx.DB.Create(&message).Error; err != nil {
			return nil, errors.New(err.Error())
		}
		return message, nil
	})

	http.HandleFunc("/tether", engine.Handle)
	log.Fatal(http.ListenAndServe(":8080", nil))
}

On the frontend, useQuery stays in sync with the backend automatically:

import { useMutation, useQuery } from "@tetherdb/react"

export const Room = () => {
	const { data: messages, error } = useQuery("getMessages", { room: "general" })
	const { mutate } = useMutation("sendMessage")

	return (
		<div>
			{messages?.map((msg) => <p key={msg.id}>{msg.body}</p>)}
			<button onClick={() => mutate({ room: "general", body: "Hello!" })}>Say hello</button>
		</div>
	)
}

To scale this app horizontally, replace sqlite.Open("app.db") with postgres.Open(dsn) and run as many copies as you need.

The documentation covers authentication, file storage, scheduling, transactions, profiling, deployment, and the full client API.

Requirements

  • Go 1.26 or newer
  • SQLite or PostgreSQL. PostgreSQL is required for horizontal scaling.

Contributing

Contributions are welcome. Please read CONTRIBUTING.md before opening a pull request, and report security issues privately through GitHub's vulnerability reporting.

License

Licensed under the Apache License 2.0.

Documentation

Overview

Package tether is a reactive backend framework. Queries and mutations are plain Go functions registered on an Engine; clients subscribe to queries over a WebSocket, and Tether re-runs a query and pushes the new result whenever a mutation writes data that the query depends on.

A typical server creates an engine, registers its tables, guards, queries and mutations, and mounts the engine's HTTP handlers:

engine, err := tether.NewEngine(db)
if err != nil {
	log.Fatal(err)
}
defer engine.Close()
engine.CreateTable(&Message{})
engine.RegisterQuery("getMessages", getMessages)
engine.RegisterMutation("sendMessage", sendMessage)
http.HandleFunc("/tether", engine.Handle)

Queries depend automatically on the primary keys of the rows they load. Use QueryCtx.TrackCollection or QueryCtx.TrackTable to also pick up rows that are inserted later. Writes made through MutationCtx.DB are detected automatically, so mutations never notify clients themselves.

With SQLite, Tether runs as a single instance. With PostgreSQL, any number of engines can share one database: writes on one instance update subscribers on every instance, and each scheduled task runs exactly once across the cluster.

Index

Constants

View Source
const (
	ContextKeyExecutionID traceContextKey = "exec_id"
	ContextKeyActionName  traceContextKey = "action_name"
)

Context keys set on the context of the *gorm.DB given to queries, guards and mutations. Both values are strings: ContextKeyExecutionID holds an ID unique to one execution, and ContextKeyActionName holds the name of the query, guard or mutation. GORM callbacks and loggers can read them with db.Statement.Context.Value(tether.ContextKeyExecutionID).

Variables

View Source
var ErrEngineClosed = errors.New("tether: engine is closed")

ErrEngineClosed is returned by SchedulerCtx.RunAfter once Engine.Close has been called, and by Engine.SetStorage if it is called after close.

View Source
var ErrNoCaller = errors.New("tether: no caller")

ErrNoCaller is returned by AuthCtx.GetIdentity when a query or mutation runs without a caller: scheduled tasks, crons, and calls to Engine.ExecuteQuery or Engine.ExecuteMutation.

View Source
var ErrProfilerRunning = errors.New("tether: profiler is already running")

ErrProfilerRunning is returned when starting a profiler that is already running.

Functions

This section is empty.

Types

type ActionCtx added in v1.4.0

type ActionCtx struct {
	// Auth identifies the caller from the request's Authorization header.
	// See [Engine.HTTPAction].
	Auth *AuthCtx
	// Scheduler schedules mutations the same way [MutationCtx.Scheduler] does.
	Scheduler *SchedulerCtx
	// Storage manages files the same way [MutationCtx.Storage] does, including
	// [StorageCtx.RunAfterUpload].
	Storage *StorageCtx
	// Profiler is the engine's profiler, the same value [Engine.Profiler] returns.
	Profiler *Profiler
	// ExecuteMutation runs a mutation and returns its result. It is
	// [Engine.ExecuteMutation]: the nested run has no caller, even when this
	// request does, and name may be registered with [Internal].
	ExecuteMutation func(name string, params map[string]any) (any, error)
	// ExecuteQuery runs a query once and returns its result. It is
	// [Engine.ExecuteQuery]: the query is not subscribed, its result is not
	// sent to clients, its ctx.DB is read-only, and there is no caller. name
	// may be registered with [Internal].
	ExecuteQuery func(name string, params map[string]any) (any, error)
}

ActionCtx is passed to an HTTP handler wrapped with Engine.HTTPAction. The handler reads the request and writes the response itself.

type Auth

type Auth interface {
	// VerifyToken checks token and returns the user ID it belongs to and
	// when that identity expires. At expiresAt the client is told its
	// identity expired and its subscriptions re-run as anonymous. A zero
	// expiresAt means the identity does not expire.
	// Returning a different user ID than the connection had re-runs its
	// subscriptions as the new user. A non-nil error rejects the token and
	// leaves the connection's identity unchanged. ctx is cancelled when the
	// engine shuts down. DB is the engine's database.
	VerifyToken(ctx context.Context, DB *gorm.DB, token string) (userID string, expiresAt time.Time, err error)
}

Auth verifies the tokens clients send to identify themselves. Set it with Engine.SetAuth.

type AuthCtx

type AuthCtx struct {
	// GetIdentity returns the caller's user ID, or "" for an anonymous
	// client. In a query or guard, calling it makes the result depend on the
	// caller's identity: it re-runs when the client's identity changes, and
	// is shared only with clients of the same identity. An HTTP handler
	// wrapped with [Engine.HTTPAction] has a caller: the user ID from the
	// request's bearer token, or "" when that request has no Authorization
	// header. When there is no caller — a mutation run by the scheduler or a
	// cron, or a query or mutation run with [Engine.ExecuteQuery] or
	// [Engine.ExecuteMutation], including one started from an HTTP action —
	// GetIdentity returns [ErrNoCaller].
	GetIdentity func() (string, error)
	// ExecuteGuard runs the guard registered as guardName with params and
	// returns its value. In a query the value is cached and passed through
	// JSON, so numbers come back as float64 and structs as
	// map[string]interface{}; compare simple values such as bools. An HTTP
	// action can call it for the request's identity. It returns an error if
	// the guard is not registered, if the guard returns an error, when called
	// from a guard, and when there is no caller (a mutation run by the
	// scheduler or a cron, or a query or mutation run with
	// [Engine.ExecuteQuery] or [Engine.ExecuteMutation]).
	ExecuteGuard func(guardName string, params map[string]interface{}) (interface{}, error)
}

AuthCtx gives queries, guards and mutations access to the caller's identity and to guards.

type Engine

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

Engine is a Tether server. Create one with NewEngine, register tables, guards, queries and mutations, then mount Engine.Handle (and Engine.StorageHandler if file storage is used) on an HTTP server.

The Register*, Set*, CreateTable and SetStorage methods are not safe for concurrent use and must be called before the engine starts serving requests.

func NewEngine

func NewEngine(db *gorm.DB, options ...EngineOption) (*Engine, error)

NewEngine creates an engine backed by db and starts its background work. Call Engine.Close when the engine is no longer needed.

db must use the SQLite (github.com/glebarez/sqlite) or PostgreSQL (gorm.io/driver/postgres) dialector. NewEngine returns an error for any other dialector, if it cannot create the tether_tasks table, and, on PostgreSQL, if it cannot read the connection's DSN. On those failures any background work already started is shut down before the error is returned. It registers callbacks on db that detect writes and enforce read-only access for queries and guards, so db should not be shared with another engine. It also starts the task scheduler. On PostgreSQL it listens for changes made by other engines.

func (*Engine) Close added in v1.0.0

func (e *Engine) Close()

Close shuts down all engine-owned background work. It is safe to call more than once.

It cancels the scheduler, Postgres listener and storage cleanup loops, stops the profiler, and stops every pending scheduled-task and auth-expiry timer. Timer and profiler-flush callbacks that are already running are waited for; any that fire after Close has begun do nothing, and scheduling new tasks returns ErrEngineClosed.

Persisted tasks are never deleted by Close. Once in-flight callbacks have finished, the claims this instance holds on tasks it did not run are released so that another instance, or the next engine started on the same database, runs them at their scheduled time (or immediately, if overdue). If that release fails, the claims lapse when their lease expires.

func (*Engine) CreateTable

func (e *Engine) CreateTable(schema interface{}) error

CreateTable creates or migrates the table for schema, a pointer to a GORM model, using GORM's AutoMigrate, and returns any migration error.

Primary keys are always tracked. Tag a field with `tether:"track"` to make it a collection that queries can depend on with QueryCtx.TrackCollection:

type Message struct {
	ID     uint `gorm:"primaryKey"`
	RoomID string `tether:"track"`
}

func (*Engine) EphemeralID added in v0.5.0

func (e *Engine) EphemeralID() string

EphemeralID returns this engine instance's ID. A new one is generated by every NewEngine call. It marks the scheduled tasks this instance has claimed and lets it ignore its own PostgreSQL notifications.

func (*Engine) ExecuteMutation

func (e *Engine) ExecuteMutation(name string, params map[string]interface{}) (any, error)

ExecuteMutation runs the mutation name with params and returns its result.

It is safe to call from code that is not itself inside a mutation, including a goroutine that holds the engine. Writes made through the mutation's ctx.DB re-run subscribed queries the same way a client mutation does.

name may be registered with Internal. There is no caller: ctx.Auth.GetIdentity returns ErrNoCaller and ctx.Auth.ExecuteGuard returns an error. A non-nil error from the mutation, including a returned value that implements error, is returned to the caller. params are passed through unchanged.

func (*Engine) ExecuteQuery

func (e *Engine) ExecuteQuery(name string, params map[string]interface{}) (any, error)

ExecuteQuery runs the query name once with params and returns its result.

The query is not subscribed and its result is not sent to clients. It is safe to call from code that is not inside a mutation, including a goroutine that holds the engine. name may be registered with Internal. There is no caller: ctx.Auth.GetIdentity returns ErrNoCaller and ctx.Auth.ExecuteGuard returns an error. ctx.DB is read-only. A non-nil error from the query, including a returned value that implements error, is returned to the caller. params are passed through unchanged.

func (*Engine) HTTPAction added in v1.4.0

func (e *Engine) HTTPAction(fn func(ctx *ActionCtx, w http.ResponseWriter, r *http.Request)) func(w http.ResponseWriter, r *http.Request)

HTTPAction returns an HTTP handler that can call guards, queries, mutations, storage, and the scheduler.

The request's Authorization header, when present, must be a Bearer token. Auth.VerifyToken checks the token, and ctx.Auth.GetIdentity returns that user ID. A request with no Authorization header is anonymous: GetIdentity returns "" and a nil error. A header that is not a Bearer token, or a token VerifyToken rejects, makes GetIdentity return an error and an empty user ID. The handler still runs, so check that error before doing work for the caller.

ctx.Auth.ExecuteGuard uses that same identity and a read-only database. ctx.ExecuteMutation and ctx.ExecuteQuery do not. They are Engine.ExecuteMutation and Engine.ExecuteQuery, so the nested run has no caller even when the request does. Without Engine.SetAuth, every bearer token is accepted and the caller stays anonymous.

Mount the returned function like any other HTTP handler:

http.HandleFunc("POST /hooks/stripe", engine.HTTPAction(func(ctx *tether.ActionCtx, w http.ResponseWriter, r *http.Request) {
    userID, err := ctx.Auth.GetIdentity()
    if err != nil || userID == "" {
        http.Error(w, "unauthorized", http.StatusUnauthorized)
        return
    }
}))

func (*Engine) Handle

func (e *Engine) Handle(w http.ResponseWriter, r *http.Request)

Handle upgrades the request to a WebSocket connection speaking the Tether client protocol. Mount it at the path the client libraries connect to. Every JSON object frame sent on that connection includes protocol_version.

By default only same-origin browser connections are accepted; use Engine.SetAllowedOrigins or Engine.SetCheckOrigin to allow others. A client frame larger than 8 KB closes the connection.

func (*Engine) Profiler added in v0.3.0

func (e *Engine) Profiler() *Profiler

Profiler returns the engine's profiler. Recording is stopped until Profiler.Start or Profiler.StartWithCallback runs. Mutations see this same profiler as MutationCtx.Profiler.

func (*Engine) RegisterCron added in v0.5.0

func (e *Engine) RegisterCron(cronName string, cronString string, functionName string, params map[string]interface{}) (string, error)

RegisterCron runs the mutation functionName with params on the schedule cronString, and returns the cron's task ID.

cronString is a standard five-field expression (minute, hour, day of month, month, day of week), such as "0 16 1 * *", evaluated in the server's local time zone. Each occurrence runs once across all engines sharing the database. An occurrence missed while no engine was running runs once when an engine next polls.

cronName identifies the cron. Registering an existing name updates its schedule, mutation and params in place and returns the same ID, so it is safe to call RegisterCron on every startup. To remove a cron, stop registering it and pass its ID to SchedulerCtx.Cancel.

The mutation may be registered with Internal. It runs without a caller, so ctx.Auth.GetIdentity returns ErrNoCaller and ctx.Auth.ExecuteGuard returns an error. params are stored as JSON, so the mutation receives numbers as float64. functionName is not checked here; an unknown name is logged when it runs.

func (*Engine) RegisterGuard added in v0.4.0

func (e *Engine) RegisterGuard(name string, fn func(ctx *GuardCtx) (any, error), opts ...GuardOption)

RegisterGuard registers fn as the guard name. It panics if name is already registered. Queries and mutations run guards with ctx.Auth.ExecuteGuard; guards cannot run other guards.

A guard is a reusable authorization check. fn returns the check's value and an error. The value must be encodable as JSON. A non-nil error fails the guard: AuthCtx.ExecuteGuard returns it, and a later re-run drops the cached result so a query cannot keep a grant that could not be rechecked. A value that implements error fails the guard the same way.

Inside a query the value is cached per user and params, and the guard is re-run when its own dependencies change (tracked the same way as a query's, through ctx.DB, TrackCollection, TrackTable and GetIdentity). If the value changes, the queries that used it re-run. Subscribers whose guards returned the same value can still share one query execution.

ctx.DB is read-only: any write fails.

opts accepts GuardOption values. None are defined yet; the parameter is reserved so options can be added without changing this signature.

func (*Engine) RegisterMutation

func (e *Engine) RegisterMutation(name string, fn func(ctx *MutationCtx) (any, error), opts ...Option)

RegisterMutation registers fn as the mutation name. It panics if name is already registered.

fn returns the value sent to the calling client and an error. The value is encoded as JSON. A non-nil error is sent as an error frame containing err.Error() instead; that text is sent verbatim, so it should not reveal internal details. A value that implements error is treated the same way. An internal mutation has no client, so its error is returned to whoever ran it: Engine.ExecuteMutation, the scheduler, or a cron.

Writes made through ctx.DB with GORM's Create, Save, Update(s) and Delete re-run every subscribed query that depends on the changed rows. Writes inside a transaction do so only once it commits. Raw SQL run with Exec is not detected.

Options are applied in order. Internal hides the mutation from clients, who receive the same error as for an unknown name, but it can still be run with Engine.ExecuteMutation, SchedulerCtx.RunAfter, or Engine.RegisterCron.

func (*Engine) RegisterQuery

func (e *Engine) RegisterQuery(name string, fn func(ctx *QueryCtx) (any, error), opts ...Option)

RegisterQuery registers fn as the live query name. It panics if name is already registered.

When a client subscribes, fn runs and its return value is encoded as JSON and sent to the client. That first run does not block the connection, so other subscriptions on the same connection are evaluated at the same time. fn runs again, and the new result is pushed, whenever something it depends on changes. A query depends on:

  • the primary keys of every row it loads through ctx.DB (automatic);
  • collections and tables named with QueryCtx.TrackCollection and QueryCtx.TrackTable;
  • the caller's identity, if it calls ctx.Auth.GetIdentity;
  • the result of every guard it runs with ctx.Auth.ExecuteGuard.

Primary-key tracking cannot see rows inserted after the query ran, so a query that lists rows should also track their collection or table.

Subscriptions with the same query, params and identity-related state share one execution of fn, so its result must depend only on ctx. ctx.DB is read-only: any write fails. fn returns the value sent to the client and an error. The value is encoded as JSON. A non-nil error is sent as an error frame containing err.Error(). A value that implements error is treated the same way.

Options are applied in order. Clients cannot subscribe to a query registered with Internal and receive the same error as for an unknown name. Engine.ExecuteQuery can still run it.

func (*Engine) SetAllowedOrigins

func (e *Engine) SetAllowedOrigins(allowedOrigins []string)

SetAllowedOrigins allows the listed origins for WebSocket upgrades and storage routes. Browsers calling those storage routes from an allowed origin receive the CORS headers the request needs.

func (*Engine) SetAuth

func (e *Engine) SetAuth(auth Auth)

SetAuth sets how clients authenticate. When a client sends a token, the engine passes it to auth.VerifyToken and binds the returned user ID to that connection. Without SetAuth, every token is accepted and the client stays anonymous.

func (*Engine) SetCheckOrigin

func (e *Engine) SetCheckOrigin(checkOrigin func(r *http.Request) bool)

SetCheckOrigin sets the function that accepts or rejects browser origins. It applies to WebSocket upgrades and to storage routes served by the engine.

func (*Engine) SetStorage added in v1.0.0

func (e *Engine) SetStorage(adapter storage.StorageAdapter, basePath string, defaults ...storage.UploadOption) error

SetStorage enables file storage through the given adapter, such as local.New or s3.New. basePath is the URL prefix for the upload, download, and public routes. An empty basePath uses "/storage", so those routes are PUT {basePath}/upload/{token}, GET {basePath}/file/{token}, and GET {basePath}/public/{fileID}. Mount Engine.StorageHandler at that prefix, without http.StripPrefix, so clients can reach the URLs. The path must start with "/" and must not contain "..". A trailing slash is removed.

defaults apply to every later GetUploadURL, PutFile, and GetDownloadURL. Options passed to those calls apply after them, in order. Nil options are ignored. A zero size or lifetime selects the built-in default of 20 MB or 15 minutes. storage.Public among the defaults marks every upload public. storage.WithDownloadExpiresIn and storage.UseCachedURLs apply when a download URL is issued. PutFile honors Public and ignores size, lifetime, and download-URL defaults.

It creates the storage tables and starts an hourly cleanup of expired download links and abandoned uploads. Call it at most once. An invalid basePath is rejected before any of that work starts. If creating the tables fails, SetStorage returns that error and leaves the engine running, with storage still disabled. If the engine is already closed, it returns ErrEngineClosed.

func (*Engine) StorageHandler added in v0.7.0

func (e *Engine) StorageHandler(w http.ResponseWriter, r *http.Request)

StorageHandler serves upload, download, and public file URLs. By default those are PUT /storage/upload/{token}, which stores the request body as the file, GET /storage/file/{token}, which serves a file to anyone holding a download link from StorageCtx.GetDownloadURL, and GET /storage/public/{fileID}, which serves a file marked public with storage.Public. A file that is missing, private, or not yet active is not found. Engine.SetStorage can replace the "/storage" prefix. The handler matches the full request path, so mount it at that prefix without http.StripPrefix:

http.HandleFunc("/storage/", engine.StorageHandler)

Served files include X-Content-Type-Options: nosniff. Types that are not safe to display in the browser, including SVG, are sent as attachments. An upload request may include headers named X-Tether-Meta-*. A mutation registered with StorageCtx.RunAfterUpload receives them, along with the stored file's id, size, type, and visibility. That mutation runs in the background after the file is stored. Its error is logged and is not returned to the client. The upload still succeeds when the mutation fails. Browser requests are subject to the same origin policy as Engine.Handle, and allowed origins receive the CORS headers they need. Responses vary on Origin even when the request omits it, so a cached media load of the same URL cannot satisfy a later cross-origin fetch. Responds with 501 Not Implemented if Engine.SetStorage has not been called.

type EngineOption added in v1.0.0

type EngineOption func(*engineConfig) error

EngineOption configures an engine created by NewEngine. None are defined yet. The parameter is reserved so options can be added without changing NewEngine's signature.

type GuardCtx added in v0.4.0

type GuardCtx struct {
	// DB is a read-only handle to the engine's database. Rows loaded through
	// it are tracked by primary key automatically.
	DB   *gorm.DB
	Auth *AuthCtx
	// Params holds the parameters passed to ExecuteGuard.
	Params map[string]interface{}
	// contains filtered or unexported fields
}

GuardCtx is passed to guard functions registered with Engine.RegisterGuard.

func (*GuardCtx) TrackCollection added in v0.4.0

func (c *GuardCtx) TrackCollection(tableName string, columnName string, value interface{})

TrackCollection is like QueryCtx.TrackCollection, but makes the guard re-run.

func (*GuardCtx) TrackTable added in v0.4.0

func (c *GuardCtx) TrackTable(tableName string)

TrackTable is like QueryCtx.TrackTable, but makes the guard re-run.

type GuardOption added in v1.0.0

type GuardOption func(*guardConfig)

GuardOption configures a guard registered with Engine.RegisterGuard. None are defined yet. The parameter is reserved so options can be added without changing RegisterGuard's signature.

type Metric added in v1.0.0

type Metric struct {
	ID       string        // The id of the metric
	Name     string        // The name of the metric
	Type     MetricType    // The type of the metric
	Time     time.Time     // The time the metric was recorded
	Duration time.Duration // The duration of the metric
	Value    int           // The value of the metric
	Tags     []string      // The tracking tags of the metric
}

Metric is one raw timing span recorded by the Profiler. Spans from the same query, mutation or guard execution share an ID. Use SanitizeMetrics to turn a batch of metrics into a report.

type MetricType added in v1.0.0

type MetricType string

MetricType is the kind of work a Metric measures.

const (
	MetricTypeQuery          MetricType = "query"
	MetricTypeMutation       MetricType = "mutation"
	MetricTypeDatabase       MetricType = "database"
	MetricTypeCache          MetricType = "cache"
	MetricTypeRouting        MetricType = "routing"
	MetricTypeAuthentication MetricType = "authentication"
)

Metric types recorded by the engine.

type MutationCtx

type MutationCtx struct {
	// DB is a read-write handle to the engine's database. Writes made through
	// it re-run the queries that depend on the changed rows.
	DB        *gorm.DB
	Auth      *AuthCtx
	Scheduler *SchedulerCtx
	// Params holds the parameters sent by the client, decoded from JSON.
	// They are untrusted input, and numbers arrive as float64.
	Params map[string]interface{}
	// Profiler is the engine's profiler, the same value [Engine.Profiler] returns.
	Profiler *Profiler
	Storage  *StorageCtx
	// ExecuteMutation runs another mutation and returns its result. It is
	// [Engine.ExecuteMutation]: the nested run has no caller, even when this
	// mutation does, writes through its ctx.DB re-run subscribed queries, and
	// name may be registered with [Internal]. params are passed through
	// unchanged.
	ExecuteMutation func(mutationName string, params map[string]interface{}) (any, error)
	// ExecuteQuery runs a query once and returns its result. It is
	// [Engine.ExecuteQuery]: the query is not subscribed, its result is not
	// sent to clients, its ctx.DB is read-only, and there is no caller. name
	// may be registered with [Internal]. params are passed through unchanged.
	ExecuteQuery func(queryName string, params map[string]interface{}) (any, error)
}

MutationCtx is passed to mutation functions registered with Engine.RegisterMutation.

type Option added in v1.0.0

type Option func(*optionConfig)

Option configures a query or mutation registered with Engine.RegisterQuery or Engine.RegisterMutation.

func Internal added in v1.0.0

func Internal() Option

Internal hides a query or mutation from clients. They receive the same error as for an unknown name. Engine.ExecuteQuery, Engine.ExecuteMutation, MutationCtx.ExecuteQuery, and MutationCtx.ExecuteMutation can still run it, and an internal mutation can still be run by the scheduler and by crons.

type ProfileAggregate added in v1.0.0

type ProfileAggregate struct {
	Name        string        `json:"name"`
	Type        MetricType    `json:"type"`
	Count       int           `json:"count"`
	TotalSum    time.Duration `json:"total_sum"`
	LogicSum    time.Duration `json:"logic_sum"`
	DatabaseSum time.Duration `json:"database_sum"`
	CacheSum    time.Duration `json:"cache_sum"`
	RoutingSum  time.Duration `json:"routing_sum"`
	AuthSum     time.Duration `json:"auth_sum"`
	TotalAvg    time.Duration `json:"total_avg"`
	LogicAvg    time.Duration `json:"logic_avg"`
	DatabaseAvg time.Duration `json:"database_avg"`
	RoutingAvg  time.Duration `json:"routing_avg"`
	TotalMin    time.Duration `json:"total_min"`
	TotalMax    time.Duration `json:"total_max"`
}

ProfileAggregate rolls up every execution that shares a sanitized name.

type ProfileOp added in v1.0.0

type ProfileOp struct {
	Name     string        `json:"name"`
	Type     MetricType    `json:"type"`
	Time     time.Time     `json:"time"`
	Duration time.Duration `json:"duration"`
	Value    int           `json:"value,omitempty"`
	Tags     []string      `json:"tags,omitempty"`
}

ProfileOp is a single recorded span inside an execution.

type ProfileReport added in v1.0.0

type ProfileReport struct {
	Totals     ProfileTotals       `json:"totals"`
	Aggregates []ProfileAggregate  `json:"aggregates"`
	Executions []ProfiledExecution `json:"executions"`
}

ProfileReport is a sanitized, execution-batched view of raw profiler metrics.

func SanitizeMetrics added in v1.0.0

func SanitizeMetrics(metrics []Metric) ProfileReport

SanitizeMetrics groups raw metrics by execution ID and rewrites query and mutation wall clocks into component times. Database spans are summed; overlapping routing spans (cumulative batch_execution vs invalidate_tags) are collapsed so Logic is max(0, Total - Database - Cache - Routing - Auth).

func (ProfileReport) Slowest added in v1.0.0

func (r ProfileReport) Slowest(n int) []ProfiledExecution

Slowest returns the n executions with the largest Total, longest first.

func (ProfileReport) String added in v1.0.0

func (r ProfileReport) String() string

String formats the report as a human-readable summary: overall totals, a breakdown by name, and the 15 slowest executions.

type ProfileTotals added in v1.0.0

type ProfileTotals struct {
	Executions int           `json:"executions"`
	Total      time.Duration `json:"total"`
	Logic      time.Duration `json:"logic"`
	Database   time.Duration `json:"database"`
	Cache      time.Duration `json:"cache"`
	Routing    time.Duration `json:"routing"`
	Auth       time.Duration `json:"auth"`
}

ProfileTotals is the report-wide sum of each component.

type ProfiledExecution added in v1.0.0

type ProfiledExecution struct {
	ID        string     `json:"id"`
	Name      string     `json:"name"`
	Type      MetricType `json:"type"`
	StartedAt time.Time  `json:"started_at"`
	Tags      []string   `json:"tags,omitempty"`

	Total    time.Duration `json:"total"`
	Logic    time.Duration `json:"logic"`
	Database time.Duration `json:"database"`
	Cache    time.Duration `json:"cache"`
	Routing  time.Duration `json:"routing"`
	Auth     time.Duration `json:"auth"`

	DatabaseOps []ProfileOp `json:"database_ops,omitempty"`
	CacheOps    []ProfileOp `json:"cache_ops,omitempty"`
	RoutingOps  []ProfileOp `json:"routing_ops,omitempty"`
	AuthOps     []ProfileOp `json:"auth_ops,omitempty"`
	OtherOps    []ProfileOp `json:"other_ops,omitempty"`
}

ProfiledExecution is one execution ID with nested work rolled up into non-overlapping components. Logic is the parent query/mutation wall time minus nested database (and cache/routing/auth) time.

type Profiler added in v1.0.0

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

Profiler collects Metric values while it is running. Recording is nearly free while it is stopped. At most 100,000 metrics are buffered between flushes; later ones are dropped. A Profiler is safe for concurrent use.

func (*Profiler) Add added in v1.0.0

func (p *Profiler) Add(m Metric)

Add records m if the profiler is running, and does nothing otherwise.

func (*Profiler) DumpMetricsAndFlush added in v1.0.0

func (p *Profiler) DumpMetricsAndFlush() []Metric

DumpMetricsAndFlush returns the metrics recorded since the last call and clears the buffer. It returns nil if there are none.

func (*Profiler) IsActive added in v1.0.0

func (p *Profiler) IsActive() bool

IsActive reports whether the profiler is running.

func (*Profiler) Start added in v1.0.0

func (p *Profiler) Start() error

Start starts recording metrics. Collect them with DumpMetricsAndFlush. It returns ErrProfilerRunning if the profiler is already running.

func (*Profiler) StartWithCallback added in v1.0.0

func (p *Profiler) StartWithCallback(flushInterval time.Duration, mutationName string) error

StartWithCallback starts recording metrics and, every flushInterval, calls the profiler's flush callback with mutationName. On the engine's profiler this runs the mutation mutationName with no params and no caller; that mutation (usually Internal) should call ctx.Profiler.DumpMetricsAndFlush and store or log the result. It returns ErrProfilerRunning if the profiler is already running.

func (*Profiler) Stop added in v1.0.0

func (p *Profiler) Stop()

Stop stops recording and stops the flush callback, if any. Metrics already recorded stay buffered until DumpMetricsAndFlush is called. Stopping a stopped profiler does nothing.

type QueryCtx

type QueryCtx struct {
	// DB is a read-only handle to the engine's database. Rows loaded through
	// it are tracked by primary key automatically.
	DB   *gorm.DB
	Auth *AuthCtx
	// Params holds the parameters sent by the client, decoded from JSON.
	// They are untrusted input, and numbers arrive as float64.
	Params map[string]interface{}

	Storage *StorageCtx
	// contains filtered or unexported fields
}

QueryCtx is passed to query functions registered with Engine.RegisterQuery.

func (*QueryCtx) TrackCollection

func (c *QueryCtx) TrackCollection(tableName string, columnName string, value interface{})

TrackCollection makes the query re-run whenever a row in tableName whose columnName equals value is created, updated or deleted, including rows that move into or out of the collection. tableName and columnName are database names, such as "messages" and "room_id", and the column's model field must be tagged `tether:"track"`. value is compared by its fmt.Sprint form.

func (*QueryCtx) TrackTable

func (c *QueryCtx) TrackTable(tableName string)

TrackTable makes the query re-run whenever any row in tableName is created, updated or deleted. Prefer TrackCollection when the query reads only part of the table.

type SchedulerCtx added in v0.5.0

type SchedulerCtx struct {
	// RunAfter runs the mutation functionName with params once duration has
	// passed, and returns the task's ID. The mutation may be registered with
	// [Internal]. It runs without a caller, so its ctx.Auth.GetIdentity
	// returns [ErrNoCaller], and params are stored as JSON, so it receives
	// numbers as float64. The task is saved outside any transaction ctx.DB is in and
	// stays scheduled even if that transaction rolls back. RunAfter returns
	// [ErrEngineClosed] once the engine is closed.
	RunAfter func(duration time.Duration, functionName string, params map[string]interface{}) (string, error)
	// Cancel removes the task or cron with the given ID so it does not run
	// again. It returns false if the task could not be deleted or has
	// already started running on this engine. A run already in progress on
	// another engine is not interrupted.
	Cancel func(taskID string) bool
}

SchedulerCtx schedules mutations to run later. Scheduled tasks are stored in the database, survive restarts, and run once across all engines sharing the database.

type StorageCtx added in v0.7.0

type StorageCtx struct {
	// GetUploadURL creates a file record and returns its ID with a single-use
	// upload URL. The client uploads the file by sending its raw bytes, with
	// a Content-Type header, in a PUT request to that URL. Store the FileID in
	// your own tables to refer to the file later. The upload is limited to
	// 20 MB and must start within 15 minutes, unless changed with
	// [storage.WithMaxBytes] or [storage.WithExpiresIn]. Options passed to
	// [Engine.SetStorage] are applied first; opts are applied after them, in
	// order. A zero size or lifetime selects the built-in default. The upload
	// URL uses the base path passed to SetStorage, or /storage when that path
	// is empty.
	// Not available in queries.
	GetUploadURL func(opts ...storage.UploadOption) (storage.UploadInfo, error)
	// GetDownloadURL returns a URL that serves the file to anyone who has it.
	// It does not check that the file exists or that the caller may read it,
	// so authorize the caller first. The URL stays valid for 15 minutes
	// unless [storage.WithDownloadExpiresIn] says otherwise. Options passed
	// to [Engine.SetStorage] are applied first; opts are applied after them.
	// [storage.UseCachedURLs] returns an existing URL for fileID when that
	// URL has more than five minutes left, instead of issuing a new one.
	// While a cached URL is returned, a different WithDownloadExpiresIn on
	// that call is ignored.
	//
	// A subscribed query that calls GetDownloadURL depends on the URL's
	// token. Storage cleanup deletes the token once it expires and re-runs
	// the query, which can return a fresh URL. The URL uses the base path
	// passed to [Engine.SetStorage], or /storage when that path is empty.
	GetDownloadURL func(fileID string, opts ...storage.UploadOption) (string, error)
	// DeleteFile deletes the file's contents and record, and invalidates its
	// download URLs. Not available in queries.
	DeleteFile func(fileID string) error

	// PutFile stores data and returns the file's ID. The record is active
	// immediately. Store that ID in your own tables to refer to the file later.
	//
	// contentType is saved as the file's MIME type and sent when the file is
	// served. data is read to completion. The upload has no size or lifetime
	// limit: [storage.WithMaxBytes], [storage.WithExpiresIn],
	// [storage.WithDownloadExpiresIn], and [storage.UseCachedURLs] are
	// ignored. [storage.Public] is honored, including when it was passed to
	// [Engine.SetStorage], and a public file can be fetched at
	// {basePath}/public/{fileID} with no download token.
	//
	// Returns an error if storage is not configured. Not available in queries.
	PutFile func(contentType string, data io.Reader, opts ...storage.UploadOption) (string, error)

	// RunAfterUpload runs mutationName once the client finishes uploading
	// fileID. fileID comes from [StorageCtx.GetUploadURL]. The mutation runs
	// in the background after the file is stored and marked active, so the
	// upload response does not wait for it and does not report its error. A
	// failed mutation is logged and is not retried. The hook is removed when
	// the upload succeeds, and also when an abandoned upload is cleaned up.
	//
	// params are stored as JSON, so the mutation receives numbers as float64.
	// A nil params map is accepted. These keys are set when the
	// mutation runs, replacing any value params already had:
	//
	//	storage.fileID     the file's ID
	//	storage.fileSize   the upload's Content-Length, or -1 when it was omitted
	//	storage.mimeType   the upload's Content-Type, or application/octet-stream
	//	storage.public     whether the file is public
	//	storage.expiresAt  when the upload URL would have expired (time.Time)
	//	storage.createdAt  when the upload URL was created (time.Time)
	//
	// Headers on the upload request named X-Tether-Meta-* are copied in as
	// metadata.<name>, with <name> lowercased. X-Tether-Meta-Room: general
	// arrives as metadata.room = "general".
	//
	// One file has one hook. A second call for the same fileID returns an
	// error. The mutation may be registered with [Internal]. It runs without
	// a caller, the same way as [Engine.ExecuteMutation].
	//
	// Returns an error if the hook cannot be saved, including when
	// [Engine.SetStorage] has not been called. Not available in queries.
	RunAfterUpload func(fileID string, mutationName string, params map[string]interface{}) error
}

StorageCtx manages files stored through the adapter passed to Engine.SetStorage. Every function returns an error if storage is not configured. File URLs are paths served by Engine.StorageHandler.

type TetherDownloadToken added in v0.7.0

type TetherDownloadToken struct {
	Token     string    `gorm:"primaryKey"`
	FileID    string    `gorm:"index"`
	ExpiresAt time.Time `gorm:"index"` // time when the download token expires
}

TetherDownloadToken is the database model for a download link issued by StorageCtx.GetDownloadURL.

type TetherStorage added in v0.7.0

type TetherStorage struct {
	ID        string `gorm:"primaryKey"`  // file ID
	Token     string `gorm:"uniqueIndex"` // token used to upload the file
	Status    string `gorm:"index"`       // status of the upload (pending, uploading, active)
	FileSize  int64
	MaxBytes  int64     // maximum size allowed at upload time
	MimeType  string    // MIME type of the file
	Adapter   string    // adapter used to store the file (local, s3, etc.), helpful for migrations
	Public    bool      // whether the file is public (can be accessed without a token)
	ExpiresAt time.Time `gorm:"index"` // time when the upload token expires
	CreatedAt time.Time // time when the upload token was created
}

TetherStorage is the database model for a stored file, created by StorageCtx.GetUploadURL or StorageCtx.PutFile in the table set up by Engine.SetStorage.

type TetherTask added in v0.5.0

type TetherTask struct {
	ID           string `gorm:"primaryKey"`
	Name         string `gorm:"uniqueIndex:idx_tether_cron_name,where:is_cron = true"` // unique among crons; one-shot tasks leave this empty
	FunctionName string `gorm:"not null"`
	ParamsJSON   string
	ExecuteAt    time.Time `gorm:"index"`
	ClaimedBy    *string   `gorm:"index"`
	LockedUntil  *time.Time

	// Cron specific (Can be empty for runAfter tasks)
	CronString   *string // e.g., "0 16 1 * *"
	LastExecuted *time.Time
	IsCron       bool
}

TetherTask is the database model for scheduled tasks and crons, stored in the tether_tasks table. The engine creates and manages these rows; the type is exported so applications can inspect pending work.

type TetherUploadHook added in v1.4.0

type TetherUploadHook struct {
	FileID       string `gorm:"primaryKey"` // file the hook waits on
	MutationName string `gorm:"not null"`   // mutation run after the upload
	ParamsJSON   string `gorm:"type:text;not null"`
	CreatedAt    time.Time
}

TetherUploadHook is the database row for a mutation registered with StorageCtx.RunAfterUpload. One file has one hook. The row is removed after that upload completes, and when an abandoned upload is cleaned up.

Directories

Path Synopsis
auth
clerk
Package clerk verifies Clerk session tokens for Tether.
Package clerk verifies Clerk session tokens for Tether.
oidc
Package oidc verifies OpenID Connect ID tokens for Tether.
Package oidc verifies OpenID Connect ID tokens for Tether.
internal
Package storage defines the interface between the Tether engine and the backends that hold uploaded files.
Package storage defines the interface between the Tether engine and the backends that hold uploaded files.
local
Package local provides a storage adapter that keeps files in a directory on the server's disk.
Package local provides a storage adapter that keeps files in a directory on the server's disk.
s3
Package s3 provides a storage adapter for Amazon S3 and S3-compatible services such as MinIO, Cloudflare R2 and DigitalOcean Spaces.
Package s3 provides a storage adapter for Amazon S3 and S3-compatible services such as MinIO, Cloudflare R2 and DigitalOcean Spaces.

Jump to

Keyboard shortcuts

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