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
- Variables
- type Auth
- type AuthCtx
- type Engine
- func (e *Engine) Close()
- func (e *Engine) CreateTable(schema interface{}) error
- func (e *Engine) EphemeralID() string
- func (e *Engine) ExecuteMutation(name string, params map[string]interface{}) (any, error)
- func (e *Engine) ExecuteQuery(name string, params map[string]interface{}) (any, error)
- func (e *Engine) Handle(w http.ResponseWriter, r *http.Request)
- func (e *Engine) Profiler() *Profiler
- func (e *Engine) RegisterCron(cronName string, cronString string, functionName string, ...) (string, error)
- func (e *Engine) RegisterGuard(name string, fn func(ctx *GuardCtx) (any, error), opts ...GuardOption)
- func (e *Engine) RegisterMutation(name string, fn func(ctx *MutationCtx) (any, error), opts ...Option)
- func (e *Engine) RegisterQuery(name string, fn func(ctx *QueryCtx) (any, error), opts ...Option)
- func (e *Engine) SetAllowedOrigins(allowedOrigins []string)
- func (e *Engine) SetAuth(auth Auth)
- func (e *Engine) SetCheckOrigin(checkOrigin func(r *http.Request) bool)
- func (e *Engine) SetStorage(adapter storage.StorageAdapter, basePath string, ...) error
- func (e *Engine) StorageHandler(w http.ResponseWriter, r *http.Request)
- type EngineOption
- type GuardCtx
- type GuardOption
- type Metric
- type MetricType
- type MutationCtx
- type Option
- type ProfileAggregate
- type ProfileOp
- type ProfileReport
- type ProfileTotals
- type ProfiledExecution
- type Profiler
- type QueryCtx
- type SchedulerCtx
- type StorageCtx
- type TetherDownloadToken
- type TetherStorage
- type TetherTask
Constants ¶
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 ¶
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.
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.
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 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. 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] —
// 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. 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 ¶
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
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 ¶
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 ¶
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) 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
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 ¶
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. 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 ¶
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 ¶
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 ¶
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 and download routes. An empty basePath uses "/storage", so those routes are PUT {basePath}/upload/{token} and GET {basePath}/file/{token}. 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 upload URL. Options passed to StorageCtx.GetUploadURL 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.
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 the upload and download URLs returned by StorageCtx. By default those are PUT /storage/upload/{token}, which stores the request body as the file, and GET /storage/file/{token}, which serves it. 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)
Browser requests are subject to the same origin policy as Engine.Handle, and allowed origins receive the CORS headers they need. 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
TrackCollection is like QueryCtx.TrackCollection, but makes the guard re-run.
func (*GuardCtx) TrackTable ¶ added in v0.4.0
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
}
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 and Engine.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
Add records m if the profiler is running, and does nothing otherwise.
func (*Profiler) DumpMetricsAndFlush ¶ added in v1.0.0
DumpMetricsAndFlush returns the metrics recorded since the last call and clears the buffer. It returns nil if there are none.
func (*Profiler) Start ¶ added in v1.0.0
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
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.
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 ¶
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 ¶
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
// for the next 15 minutes. It does not check that the file exists or that
// the caller may read it, so authorize the caller first. The URL uses the
// base path passed to [Engine.SetStorage], or /storage when that path is
// empty.
GetDownloadURL func(fileID string) (string, error)
// DeleteFile deletes the file's contents and record, and invalidates its
// download URLs. Not available in queries.
DeleteFile func(fileID string) 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
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 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.
Directories
¶
| Path | Synopsis |
|---|---|
|
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. |