livewire

type AuditEntry ¶

type AuditEntry struct {
	Tenant         string
	Identity       *auth.Identity
	Mutation       string
	Parameters     any
	RequestID      string
	IdempotencyKey string
	Status         int
	Duration       time.Duration
}

AuditEntry is one mutation call as the action audit of D32 records it: the tenant, the effective identity (its Real() is the real actor), the mutation, its decoded parameters, the request id, the Idempotency-Key ("" for none), the answered status and how long the call took.

type AuditStore ¶

type AuditStore interface {
	Write(ctx context.Context, entry *AuditEntry) error
}

AuditStore keeps the action audit of D32. The engine writes one entry per call whose handler ran: a mutation, an upload and every call of a batch. For a call that commits it writes the entry in the mutation's transaction (TransactionFrom(ctx)) between the handler and the idempotency record, so the entry commits and rolls back with the call (section 7); a failing Write fails the call. For a call that failed it writes the entry after the rollback, without a transaction in ctx and on a context the caller's cancellation does not reach (bounded), so the store writes it on its own: the failed calls of a batch each with the status the batch answered. A refusal before the handler (a check, a decoding, a replayed or in-flight key) writes none.

type BatchCall ¶

type BatchCall struct {
	Target     string            `json:"target"`
	Parameters map[string]string `json:"params,omitempty"`
	Body       json.RawMessage   `json:"body,omitempty"`
}

BatchCall is one call of a batch: a mutation's name, its parameters as a socket frame carries them, and its body.

type BatchRequest ¶

type BatchRequest struct {
	Body           json.RawMessage
	IdempotencyKey string
	RequestID      string
}

BatchRequest is one batch (D33) as a transport hands it to Engine.Batch: the body, a JSON array of BatchCall, the batch's one Idempotency-Key and the request id.

type BatchResult ¶

type BatchResult struct {
	Status  int             `json:"status"`
	Payload json.RawMessage `json:"payload,omitempty"`
}

BatchResult is the answer of one call of a committed batch, in the order of the calls: the status the call answers on its own and its body (absent for NoContent).

type CallDescriber ¶

type CallDescriber interface {
	DescribeCall(ctx context.Context, transactionDetails TransactionDetails) error
}

CallDescriber is the optional interface of a Transaction that runs several calls (D58): the engine calls DescribeCall before each call of a batch (D33) with that call's details, so the triggers attribute each call's writes to its own mutation and request id (D34); the postgresadapter sets livewire.actor (actor, real actor, mutation, request id) again (SET LOCAL). The call's parameters reach its audit entry only. Without it a batch's history rows carry the outer transaction's details, whose Mutation is empty. A failing DescribeCall fails the batch.

type CallRequest ¶

type CallRequest struct {
	Target         string
	Source         ParameterSource
	Body           []byte
	IdempotencyKey string
	RequestID      string
}

CallRequest is one mutation call as a transport hands it to Engine.Call: the mutation's name, the request's parameters, the raw JSON body (empty for none), the Idempotency-Key (D16, empty for none) and the request id the transaction records (D31; a new one when empty, which is what the socket does: frame ids are the client's and repeat).

type Change ¶

type Change struct {
	Table     string
	Operation ChangeOperation
	ID        string
	Partition string
}

Change is one row change a ChangeFeed reports: the table, the operation, the row's id as text and, for partitioned triggers, the value of the partition column (D25); Partition is empty otherwise.

type ChangeFeed ¶

type ChangeFeed interface {
	Run(ctx context.Context, onChange func(Change), onResync func()) error
}

ChangeFeed delivers row changes to the engine. Run blocks until ctx ends and returns ctx.Err() then, or the failure that ended the feed for good; it reconnects on its own in between. It calls onResync after every successful connect, the first included, because changes may have been missed, and onChange once per change; both are called from the feed's goroutine and must return quickly.

type ChangeOperation ¶

type ChangeOperation string

ChangeOperation is what happened to a row.

const (
	ChangeInsert ChangeOperation = "insert"
	ChangeUpdate ChangeOperation = "update"
	ChangeDelete ChangeOperation = "delete"
)

type ClientIDVersion ¶

type ClientIDVersion int

ClientIDVersion says which client-generated `id` a create accepts (D18).

const (
	ClientIDNone ClientIDVersion = iota
	UUIDv7
	UUIDv4
)

type Code ¶

type Code string

Code is the stable client-facing code of an error body. The set is closed: generated clients switch on it, so a custom code of an *auth.Error is mapped to its kind's code.

const (
	CodeInvalidRequest  Code = "invalid_request"
	CodeInvalidFilter   Code = Code(query.CodeInvalidFilter)
	CodeInvalidSort     Code = Code(query.CodeInvalidSort)
	CodeInvalidPage     Code = Code(query.CodeInvalidPage)
	CodeInvalidCursor   Code = Code(query.CodeInvalidCursor)
	CodeForbiddenField  Code = "forbidden_field"
	CodeUnauthenticated Code = "unauthenticated"
	CodeForbidden       Code = "forbidden"
	CodeNotFound        Code = "not_found"
	CodeConflict        Code = "conflict"
	CodeInProgress      Code = "in_progress"
	CodeInternal        Code = "internal"
)

type Declaration ¶

type Declaration interface {
	Kind() Kind
	Name() string
	Method() string
	Path() string
	Tables() []string
	Check() authorization.Check
	Parameters() []Parameter
	DecodeParameters(source ParameterSource) (any, error)
	// contains filtered or unexported methods
}

Declaration is one entry of the registry: a *Resource, *List, *Object, *Mutation or *Upload. The interface is sealed to those five kinds; a type that embeds one of them is refused by Registry.Add. Path is relative to the registry's BasePath and uses `{name}` placeholders. Name is the wire target and the identifier of the generated clients; Method is the HTTP method of the main REST route (GET for reads); Tables are the tables whose changes re-run the declaration's subscriptions, none means not live; Check is the static gate (D8) that runs before parameters are resolved against the database and before a body is read; Parameters describes the parameters struct for the generators; DecodeParameters fills a new parameters value (a *Parameters) from source and answers a missing path parameter, a repeated scalar parameter or a value of the wrong form with an *Error of 400 invalid_request naming the parameter.

type DistinctValue ¶

type DistinctValue struct {
	Value any `json:"value"`
	Count int `json:"count"`
}

DistinctValue is one row of a distinct read (D15): a value of the field and how many rows carry it.

type Effect ¶

type Effect struct {
	Kind   EffectKind
	Target string
}

Effect is the optimistic effect of a mutation on the live lists of Target (D36); the zero value is no effect.

func Removes(target string) Effect

func Upserts(target string) Effect

type EffectKind ¶

type EffectKind string

EffectKind is what an optimistic effect does to a live list (D36).

const (
	EffectUpserts EffectKind = "upserts" // the response is upserted into the list
	EffectRemoves EffectKind = "removes" // the item whose id is the request's `id` path parameter is removed
)

type Engine ¶

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

Engine serves an API's socket (section 4) and runs the read and write pipelines both transports share (D23): Read, Call, Batch and Upload are what the REST adapter calls, the socket ops run the same code. Build it with NewEngine, serve Handler, run Run, and end it with Close. It is safe for concurrent use.

func NewEngine(options *EngineOptions) (*Engine, error)

package main

import (
	"context"
	"fmt"
	"net/http"

	"github.com/govengers/livewire"
)

func main() {
	var (
		ctx            context.Context
		registry       *livewire.Registry      // built with NewRegistry and Add
		identitySource livewire.IdentitySource // session.Guard
		transactor     livewire.Transactor     // postgresadapter
		changeFeed     livewire.ChangeFeed     // postgresadapter's LISTEN feed
		authenticate   func(http.Handler) http.Handler
	)
	engine, err := livewire.NewEngine(&livewire.EngineOptions{
		Registry:       registry,
		ChangeFeed:     changeFeed,
		IdentitySource: identitySource,
		Transactor:     transactor,
		AllowedOrigins: []string{"https://app.example"},
	})
	if err != nil {
		fmt.Println(err)
		return
	}
	http.Handle("/api/v1/socket", authenticate(engine.Handler())) // the Go client's default socket URL
	go func() { _ = engine.Run(ctx) }()
	defer func() { _ = engine.Close(ctx) }()
}

Output:

func (e *Engine) Batch(ctx context.Context, request BatchRequest) (json.RawMessage, error)

func (e *Engine) Call(ctx context.Context, request CallRequest) (status int, payload json.RawMessage, err error)

func (e *Engine) Close(ctx context.Context) error

func (e *Engine) DeleteFilter(ctx context.Context, id string) error

func (e *Engine) Export(ctx context.Context, request ExportRequest) (rows int, err error)

func (e *Engine) Handler() http.Handler

func (e *Engine) ListFilters(ctx context.Context, resource string) (json.RawMessage, error)

func (e *Engine) Read(ctx context.Context, request ReadRequest) (json.RawMessage, error)

func (e *Engine) Registry() *Registry

func (e *Engine) RevalidateAll()

func (e *Engine) RevalidateOwner(key string)

func (e *Engine) Run(ctx context.Context) error

func (e *Engine) SaveFilter(ctx context.Context, body []byte) (json.RawMessage, error)

func (e *Engine) ServesPresence() bool

func (e *Engine) Upload(ctx context.Context, request UploadRequest) (status int, payload json.RawMessage, err error)

type EngineOptions ¶

type EngineOptions struct {
	Registry               *Registry
	ChangeFeed             ChangeFeed
	IdentitySource         IdentitySource
	Transactor             Transactor
	FilterStore            FilterStore
	IdempotencyStore       IdempotencyStore
	AuditStore             AuditStore
	PresenceStore          PresenceStore
	AllowedOrigins         []string
	SameHostOnly           bool
	SubscriptionsPerSocket int
	InFlightPerSocket      int
	PresencesPerSocket     int
	FiltersPerSocket       int
	QueuedBytesPerSocket   int
	FrameBytes             int64
	QueryConcurrency       int
	SocketsPerOwner        int
	RevalidateInterval     time.Duration
	SafetyTickInterval     time.Duration
	PresenceHeartbeat      time.Duration
	PresenceExpiry         time.Duration
	DeliveryBatchWait      time.Duration
	RetryInterval          time.Duration
	WriteTimeout           time.Duration
}

EngineOptions configures the live engine (section 5). Registry, IdentitySource and Transactor are required; AllowedOrigins is required unless SameHostOnly says that only the request's own host may open a socket (D9). ChangeFeed is optional: without one, a subscription re-runs only when its socket's identity changes and, when its filter carries a relative time, on the safety tick. FilterStore enables stored filters (D13), IdempotencyStore the replay of mutations (D16), AuditStore the action audit (D32), PresenceStore the join and leave ops and the presence reads (D37); each is optional and its feature is off without it. The engine's outcomes go to the registry's Observer (D49). The engine runs no store maintenance: the sweeps and the audit partitions (the postgresadapter's FilterStore.Sweep, IdempotencyStore.Sweep and AuditStore.Maintain) are the application's to schedule, a periodic govengers/jobs job for instance, so one replica runs them, not every engine, and a failure lands where the application handles its jobs.

The limits (D10) default when zero: SubscriptionsPerSocket 64, InFlightPerSocket 16, PresencesPerSocket 64 (records one socket may join at once), FiltersPerSocket 64 (the distinct inline filters the live subscriptions of one socket hold, D13; it bounds no filter rows beyond that socket's live ones), QueuedBytesPerSocket 8 MiB, FrameBytes 64 KiB, QueryConcurrency 32 (D52); SocketsPerOwner 0 is unlimited. The intervals default when zero: RevalidateInterval 60 s (D6, the cache of a socket's identity for re-runs and the tick that re-validates every socket), SafetyTickInterval 30 s (the re-run of time-dependent subscriptions), PresenceHeartbeat 30 s and PresenceExpiry 90 s (D37), DeliveryBatchWait 100 ms (the longest a push waits after its first change, so a burst leaves as one push per subscription), RetryInterval 1 s (the first backoff of a failed re-run or change feed, doubling up to 32 times it) and WriteTimeout 10 s (a write the client does not take in time closes its socket 1013). No value may be negative; PresenceExpiry must exceed PresenceHeartbeat.

type Error ¶

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

Error is a refusal the core or a handler answers with its status and body. Only the constructors below build one, so the code is from the closed set and the message is the code's fixed text. Match it with errors.As.

func Conflict() *Error

func ForbiddenField(name string) *Error

func InProgress() *Error

func Invalid(fields map[string]string) *Error

func NotFound() *Error

func (e *Error) Body() ErrorBody

func (e *Error) Error() string

func (e *Error) Status() int

type ErrorBody ¶

type ErrorBody struct {
	Code    Code              `json:"code"`
	Message string            `json:"message"`
	Fields  map[string]string `json:"fields,omitempty"`
}

ErrorBody is the one JSON error shape of every REST response and socket error. Message is fixed per code and safe to show; Fields names the offending parameters or body fields (nested ones as a dotted path) with a fixed text per fault.

func ResponseFor(err error) (int, ErrorBody)

type ExportRequest ¶

type ExportRequest struct {
	Target string
	Source ParameterSource
	Writer io.Writer
}

ExportRequest is one export (D35) as the REST adapter hands it to Engine.Export: the resource's name, the request's parameters (the reserved ones of a list read and `format`) and the writer the export streams to.

type File ¶

type File struct {
	ContentType string
	Size        int64
	Body        io.Reader
	Filename    string
}

File is the binary body of an upload as the handler receives it: the declared content type it matched (without parameters), its size in bytes, the body to read once, and the client's file name when a multipart part carried one.

type FilterItem ¶

type FilterItem struct {
	ID         string          `json:"id"`
	Resource   string          `json:"resource"`
	Context    string          `json:"context,omitempty"`
	Name       string          `json:"name,omitempty"`
	Filter     json.RawMessage `json:"filter"`
	CreatedAt  time.Time       `json:"createdAt"`
	LastUsedAt time.Time       `json:"lastUsedAt"`
}

FilterItem is a stored filter as the filter routes answer it: Filter is the canonical document a filterId read applies.

type FilterRequest ¶

type FilterRequest struct {
	Resource string          `json:"resource"`
	Context  string          `json:"context,omitempty"`
	Name     string          `json:"name,omitempty"`
	Filter   json.RawMessage `json:"filter"`
}

FilterRequest is the body of POST /filters (D13): the resource the filter is for (its name, or "name.history" for its history read, D56), the application's context of the dedup key ("" for none), a name ("" for an unnamed filter, which is swept after 30 days without use) and the filter document.

type FilterStore ¶

type FilterStore interface {
	// Save stores filter and returns the stored one with its ID; an unnamed filter whose
	// Hash the owner already stored for the resource and context returns that filter.
	Save(ctx context.Context, filter *StoredFilter) (*StoredFilter, error)
	// Get returns the owner's filter and marks it used; it returns NotFound when there is
	// none.
	Get(ctx context.Context, owner Owner, id string) (*StoredFilter, error)
	// List returns the owner's named filters of a resource, every resource when resource is
	// empty; unnamed filters (inline subscribe registrations) are not listed.
	List(ctx context.Context, owner Owner, resource string) ([]StoredFilter, error)
	// Delete removes the owner's filter; a filter that is not there is no error.
	Delete(ctx context.Context, owner Owner, id string) error
}

FilterStore keeps the stored filters of D13. Filters are visible to their owner only, the tenant included: every method takes the owner and treats another owner's filter as absent.

type GuardedField ¶

type GuardedField struct {
	Name string
	Read authorization.Check
}

GuardedField names a field of a typed-parameters list or object whose Read check guards it (D39): a refused check strips the field from every item.

type IdempotencyRecord ¶

type IdempotencyRecord struct {
	Owner    Owner
	Key      string
	Mutation string
	Status   int
	Response json.RawMessage
}

IdempotencyRecord is the recorded answer of a mutation call (D16): the owner, the key the client sent, the mutation it was sent for, and the status and body that were answered. Status is 0 while the call is in flight.

type IdempotencyStore ¶

type IdempotencyStore interface {
	// Reserve claims the key for the owner and mutation. A fresh key returns replay false;
	// a key whose call finished returns the record and replay true; a key whose call is
	// still in flight returns InProgress; a key recorded for another mutation returns
	// Conflict.
	Reserve(ctx context.Context, owner Owner, key, mutation string) (record *IdempotencyRecord, replay bool, err error)
	// Record stores the answer of a reserved key.
	Record(ctx context.Context, record *IdempotencyRecord) error
}

IdempotencyStore keeps the records of D16. Both methods run inside the mutation's transaction (TransactionFrom(ctx)), so a rolled-back call frees its key. Reserve must not block on another transaction's reservation of the same key: the postgresadapter takes pg_try_advisory_xact_lock over a hash of the owner and key, answers InProgress when the lock is held, replays a committed record, and inserts the reservation otherwise.

type IdentitySource ¶

type IdentitySource interface {
	Identify(ctx context.Context, request *http.Request) (*auth.Identity, error)
}

IdentitySource re-validates who a socket acts as (D6): the engine calls Identify with the upgrade request on every subscribe, query, call, batch, join and leave, on a re-run whose cached identity is older than RevalidateInterval, and on that tick (D51; ping and unsubscribe are exempt). The identity is gone, and the socket closes with CloseIdentityGone, when the source returns an error matching auth.ErrUnauthenticated (no session, expired, revoked: what session.Guard.Identify returns) or auth.ErrForbidden (a refused refresh), or a nil identity with a nil error. Any other error is a failure of the source: the engine keeps the last identity and retries.

type ItemKey ¶

type ItemKey struct {
	Parameter string
	Field     string
}

ItemKey says how a resource's item read addresses one row: the path parameter of the item route (`{Parameter}` below the resource path) and the declared field it matches, which must be filterable and of type uuid, string, text, enum, int or time. On REST the resource's own routes `distinct`, `export` and `presence` sit beside the item route and win, so an item whose key is one of these words is readable on the socket only; a key of type uuid never is.

type Kind ¶

type Kind string

Kind is the kind of a declaration.

const (
	KindResource Kind = "resource" // NewResource: a filterable list with item and distinct reads
	KindList     Kind = "list"     // NewList: a typed-parameters list
	KindObject   Kind = "object"   // NewObject: a typed-parameters object
	KindMutation Kind = "mutation" // NewMutation: a write with a JSON body
	KindUpload   Kind = "upload"   // NewUpload: a binary write, REST only
)

type List ¶

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

List is a read that answers a ListResponse of every item its loader returns for the typed parameters; it has no filter, sort or page of its own.

func NewList[Item, Parameters any](name, path string, options *ListOptions[Item, Parameters]) *List

func (s *List) Check() authorization.Check

func (s *List) DecodeParameters(source ParameterSource) (any, error)

func (l *List) Fields() query.Fields

func (l *List) ItemType() reflect.Type

func (l *List) Kind() Kind

func (l *List) Load(ctx context.Context, parameters any) (any, error)

func (s *List) Method() string

func (s *List) Name() string

func (s *List) Parameters() []Parameter

func (l *List) Partition() PartitionResolver

func (s *List) Path() string

func (s *List) Tables() []string

type ListChange ¶

type ListChange struct {
	Upserts []json.RawMessage `json:"upserts"`
	Removes []string          `json:"removes"`
	Order   []string          `json:"order,omitempty"`
	Total   *int              `json:"total,omitempty"`
}

ListChange is a list change (the wire's "diff"): replace or insert the upserted items by id, drop the removed ids, re-sort to Order when it is present (the full id list, sent when membership or order changed) and take Total when it is present (D14). Upserts and Removes are never null.

type ListOptions ¶

type ListOptions[Item, Parameters any] struct {
	Tables    []string
	Read      authorization.Check
	Partition PartitionResolver
	Guarded   []GuardedField
	Load      func(ctx context.Context, parameters *Parameters) ([]Item, error)
}

ListOptions declares a typed-parameters list. Read and Load are required; Guarded names the fields of Item whose Read check strips them (D39); a live list (Tables set) needs an item with a JSON field "id". Partition names a subscription's partition (D25); nil means the tenant.

type ListResponse ¶

type ListResponse[Item any] struct {
	Limit  int     `json:"limit"`
	Offset int     `json:"offset"`
	Total  int     `json:"total"`
	Items  []Item  `json:"items"`
	Next   *string `json:"next,omitempty"`
}

ListResponse is the body of every list read (D14): the page that was applied, the total under scope and filter (at most CountCap + 1 when the resource caps it), the items, and in cursor mode the cursor of the next page or nil at the end (D38). Items is never null.

type ListState ¶

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

ListState is what a list subscription last pushed (the engine keeps one per list subscription; a client applies ListChange the same way): every item's JSON by id, the order of the ids and the total of the list.

func NewListState(rawItems json.RawMessage, total int) (*ListState, error)

func (s *ListState) ChangesSince(previous *ListState) *ListChange

func (s *ListState) Snapshot() json.RawMessage

type MapSource ¶

type MapSource map[string]string

MapSource is a ParameterSource over one value per name, as a socket frame carries them: path and query parameters read the same map, a list parameter is one comma-separated value.

func (s MapSource) Path(name string) (string, bool)

func (s MapSource) Query(name string) ([]string, bool)

type Mutation ¶

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

Mutation is a write: a JSON body decoded with unknown fields refused (D40), checked field by field (D39), validated (D44), handled in the engine's transaction (D31).

func NewMutation[Parameters, Request, Response any](name, method, path string, options *MutationOptions[Parameters, Request, Response]) *Mutation

func (s *Mutation) Check() authorization.Check

func (m *Mutation) ClientID() ClientIDVersion

func (m *Mutation) DecodeBody(ctx context.Context, raw []byte) (any, error)

func (s *Mutation) DecodeParameters(source ParameterSource) (any, error)

func (m *Mutation) Effect() Effect

func (m *Mutation) Handle(ctx context.Context, parameters, body any) (any, error)

func (m *Mutation) HasBody() bool

func (m *Mutation) HasContent() bool

func (m *Mutation) Kind() Kind

func (s *Mutation) Method() string

func (s *Mutation) Name() string

func (s *Mutation) Parameters() []Parameter

func (m *Mutation) ParametersType() reflect.Type

func (s *Mutation) Path() string

func (m *Mutation) RequestType() reflect.Type

func (m *Mutation) Resource() string

func (m *Mutation) ResponseType() reflect.Type

func (m *Mutation) Status() int

func (s *Mutation) Tables() []string

type MutationOptions ¶

type MutationOptions[Parameters, Request, Response any] struct {
	Check       authorization.Check
	Status      int
	ClientID    ClientIDVersion
	Resource    string
	FieldChecks map[string]authorization.Check
	Effect      Effect
	Handle      func(ctx context.Context, parameters *Parameters, body *Request) (*Response, error)
}

MutationOptions declares a write. Check and Handle are required. Status is the success status (default 200; a NoContent response defaults to 204 and may set another 2xx, 204 with a response body is refused). ClientID accepts a client-generated `id` in the body of a create (POST, D18); the body of any other method may carry an id and the handler judges it. Resource names a registered resource whose field Write checks apply to the body by JSON name (D39); FieldChecks adds a check per JSON field of Request. Effect is the optimistic effect on live lists (D36). The body is validated with `validate` tags (go-playground/validator, D44) after the structural checks; a tag the validator cannot parse, on any struct reachable from Request, is a declaration error.

type NoBody ¶

type NoBody struct{}

NoBody is the request type of a mutation without a body; a request that sends one is refused.

type NoContent ¶

type NoContent struct{}

NoContent is the response type of a mutation that answers without a body (204 unless Status says otherwise).

type NoParameters ¶

type NoParameters struct{}

NoParameters is the parameters type of a declaration without parameters.

type Object ¶

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

Object is a read that answers one item for the typed parameters.

func NewObject[Item, Parameters any](name, path string, options *ObjectOptions[Item, Parameters]) *Object

func (s *Object) Check() authorization.Check

func (s *Object) DecodeParameters(source ParameterSource) (any, error)

func (o *Object) Fields() query.Fields

func (o *Object) ItemType() reflect.Type

func (o *Object) Kind() Kind

func (o *Object) Load(ctx context.Context, parameters any) (any, error)

func (s *Object) Method() string

func (s *Object) Name() string

func (s *Object) Parameters() []Parameter

func (l *Object) Partition() PartitionResolver

func (s *Object) Path() string

func (o *Object) PresencePath() string

func (s *Object) Tables() []string

type ObjectOptions ¶

type ObjectOptions[Item, Parameters any] struct {
	Tables    []string
	Read      authorization.Check
	Partition PartitionResolver
	Guarded   []GuardedField
	Load      func(ctx context.Context, parameters *Parameters) (*Item, error)
}

ObjectOptions declares a typed-parameters object. Read and Load are required; Guarded names the fields of Item whose Read check strips them (D39). Partition names a subscription's partition (D25); nil means the tenant.

type Observer ¶

type Observer func(ctx context.Context, outcome Outcome)

Observer receives outcomes synchronously with the context of the unit of work. It must not block and must be safe for concurrent use; a nil Observer means no reporting.

type Operation ¶

type Operation string

Operation is a socket request's operation (D2); the JSON field is "op".

const (
	OperationQuery       Operation = "query"       // one read, answered in the response
	OperationSubscribe   Operation = "subscribe"   // a live read; the response names the subscription, pushes follow
	OperationUnsubscribe Operation = "unsubscribe" // target is the subscription
	OperationCall        Operation = "call"        // a mutation
	OperationBatch       Operation = "batch"       // several mutations in one transaction (D33)
	OperationJoin        Operation = "join"        // presence (D37)
	OperationLeave       Operation = "leave"
	OperationPing        Operation = "ping"
)

type Outcome ¶

type Outcome struct {
	Kind         OutcomeKind
	Operation    Operation
	Target       string
	Subscription string
	Tenant       string
	Identity     *auth.Identity
	Parameters   any
	Status       int
	Err          error
	Duration     time.Duration
	Rows         int
	QueryWait    time.Duration
}

Outcome is one unit of work the engine or an adapter finished (D4, D30). Target is the declaration's name, with the read kind after a dot for a read other than the main one (D46), "batch" for a batch, "filters" for the stored filter routes, and "" when the request named no declaration (D59); Operation is set on the socket ("other" for an operation the socket does not know), empty on REST; Subscription is set for subscribe and rerun; Tenant is the resolved tenant (D42); Parameters is the decoded parameters value (a *Parameters) when they were decoded; Status is the HTTP status answered (the close code for OutcomeClose); Err is the refusal or failure, with the server-side Reason of an *auth.Error, and nil on success; Rows is the rows an export wrote; QueryWait is how long the unit waited for the engine's query slots (D52), so it is zero on REST.

type OutcomeKind ¶

type OutcomeKind string

OutcomeKind says which unit of work an Outcome reports.

const (
	OutcomeRequest     OutcomeKind = "request"      // one REST request
	OutcomeSubscribe   OutcomeKind = "subscribe"    // a subscribe op, its first load included
	OutcomeCall        OutcomeKind = "call"         // one mutation, on REST or the socket
	OutcomeBatch       OutcomeKind = "batch"        // one batch (D33)
	OutcomeRerun       OutcomeKind = "rerun"        // a subscription re-run after a change, resync or tick
	OutcomeAfterCommit OutcomeKind = "after_commit" // a mutation's transaction committed (D41)
	OutcomeOpen        OutcomeKind = "open"         // a socket was upgraded
	OutcomeClose       OutcomeKind = "close"        // a socket ended; Status is its close code (1000, 1001, 1013, 4401, ...)
	OutcomeRevalidate  OutcomeKind = "revalidate"   // a socket's identity re-validated on a tick or a Revalidate call (D6)
	OutcomeFeed        OutcomeKind = "feed"         // the change feed failed; the engine restarts it after a backoff
	OutcomeHeartbeat   OutcomeKind = "heartbeat"    // the presence heartbeat and sweep of a tick (D37)
	OutcomeExport      OutcomeKind = "export"       // one export (D35); Rows is how many rows it wrote
	OutcomeEnd         OutcomeKind = "end"          // a subscription a subscribe opened ended: unsubscribed, by an error push or with its socket
)

type Owner ¶

type Owner struct {
	Key    string
	Tenant string
}

Owner scopes a stored row to who stored it: the identity key "provider:subject" and the tenant of the request (D42, "" in a single-tenant registry). Two owners are the same only when both parts are equal; a key of another owner is a fresh key (section 6).

func OwnerOf(ctx context.Context) (Owner, bool)

type Page ¶

type Page[Item any] struct {
	Items []Item
	Total int
	Next  *query.Cursor
}

Page is one page a filterable resource's List loader returns (D14, D38, D55): the items in page order, the total under scope and filter (at most CountCap + 1 under a cap) and, when the page is full, the cursor after its last row (nil otherwise), unencoded. The engine answers Next encoded as ListResponse.next for a resource in cursor mode and ignores it otherwise, so a sort value without a cursor form fails only the reads that need the cursor. postgresadapter.ListPage returns one.

type Parameter ¶

type Parameter struct {
	Name string
	In   ParameterIn
	Type reflect.Type
	Enum []string
	List bool
}

Parameter describes one parameter of a declaration for the generators: its name on the wire, where it travels, the Go type of its struct field (pointer and slice types as declared), the enum values of an `enum:"a,b"` tag, and whether the wire carries a list. A path parameter is required, a query parameter optional.

func (p Parameter) Required() bool

type ParameterIn ¶

type ParameterIn string

ParameterIn is where a parameter travels.

const (
	InPath  ParameterIn = "path"
	InQuery ParameterIn = "query"
)

type ParameterSource ¶

type ParameterSource interface {
	Path(name string) (string, bool)
	Query(name string) ([]string, bool)
}

ParameterSource hands the decoder the raw values of a request: path values by name and query values by name, where a query key may repeat. The REST adapter builds one from the route, the engine from a RequestFrame's Parameters (MapSource).

type PartitionResolver ¶

type PartitionResolver func(ctx context.Context, parameters any) string

PartitionResolver names the partition of a subscription from the decoded parameters (a *Parameters, nil for a resource read) and the context (D25); the engine indexes subscriptions by table and partition and partitioned triggers carry the row's column. Without one the tenant of D42 is the partition.

type Presence ¶

type Presence struct {
	Socket    string
	Owner     Owner
	Display   string
	Target    string
	Key       string
	State     json.RawMessage
	UpdatedAt time.Time
}

Presence is one socket's presence on a target record (D37): the socket, its owner and display name, the target and key that name the record, and the client's state.

type PresenceItem ¶

type PresenceItem struct {
	ID      string          `json:"id"`
	Display string          `json:"display"`
	State   json.RawMessage `json:"state"`
}

PresenceItem is one presence as a presence read answers it: the socket that joined, its display name and the state it sent.

type PresenceStore ¶

type PresenceStore interface {
	// Join inserts or updates the socket's presence on the record.
	Join(ctx context.Context, presence *Presence) error
	// Leave removes the socket's presence on the tenant's record; an absent one is no error.
	Leave(ctx context.Context, tenant, socket, target, key string) error
	// Heartbeat refreshes UpdatedAt of every presence of the socket.
	Heartbeat(ctx context.Context, socket string) error
	// List returns the presences on a record of the tenant; a store may bound how many it
	// returns (postgresadapter: 1000, by socket).
	List(ctx context.Context, tenant, target, key string) ([]Presence, error)
	// Sweep removes every presence older than maximumAge and returns how many.
	Sweep(ctx context.Context, maximumAge time.Duration) (int, error)
}

PresenceStore keeps the rows of D37; a change to them reaches the engine through the ChangeFeed like any other table. A record is named by tenant, target and key.

type PushFrame ¶

type PushFrame struct {
	Subscription string          `json:"sub"`
	Sequence     int64           `json:"seq"`
	Kind         PushKind        `json:"kind"`
	Payload      json.RawMessage `json:"payload"`
}

PushFrame is one change of a subscription; Sequence counts from 1 per subscription.

type PushKind ¶

type PushKind string

PushKind says what a push carries.

const (
	PushSnapshot   PushKind = "snapshot" // a list's full ListResponse body: the first push and after a resync
	PushListChange PushKind = "diff"     // a ListChange against the last pushed list
	PushReplace    PushKind = "replace"  // an object's full body
	PushError      PushKind = "error"    // an ErrorBody; the subscription has ended
)

type ReadKind ¶

type ReadKind string

ReadKind says which read of a declaration a request names. On the socket it is the target's suffix after a dot (D46): "parts" is the main read, "parts.item" the item read, "parts.distinct" the distinct read, "parts.history" the versions of one item, "parts.presence" the presences on one record.

const (
	ReadMain     ReadKind = ""         // a resource's or list's ListResponse, an object's item
	ReadItem     ReadKind = "item"     // a resource's item read, keyed by its ItemKey parameter
	ReadDistinct ReadKind = "distinct" // a resource's distinct read (D15), the `field` parameter names the field
	ReadHistory  ReadKind = "history"  // a versioned resource's versions of one item (D34), keyed like the item read
	ReadPresence ReadKind = "presence" // the presences on the record named by the `key` parameter (D37)
)

type ReadParameters ¶

type ReadParameters struct {
	Filter   json.RawMessage
	FilterID string
	Sort     string
	Limit    string
	Offset   string
	After    string
	Field    string
}

ReadParameters are the reserved parameters of one resource read as the client sent them. Filter is the inline document, or the stored one the engine resolved from FilterID.

func ReadParametersFrom(source ParameterSource) (*ReadParameters, error)

type ReadRequest ¶

type ReadRequest struct {
	Target string
	Kind   ReadKind
	Source ParameterSource
}

ReadRequest is one read as a transport hands it to Engine.Read: the declaration's name, the read kind and the request's parameters, path and query.

type Registry ¶

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

Registry is the single source of truth of an API: every declaration by name, in declaration order. Build it in main with Add; it is read-only afterwards and safe for concurrent reads.

func NewRegistry(options *RegistryOptions) (*Registry, error)

func (r *Registry) Add(declarations ...Declaration) error

package main

import (
	"context"
	"fmt"
	"net/http"
	"time"

	"github.com/google/uuid"
	"github.com/govengers/auth"
	"github.com/govengers/auth/authorization"

	"github.com/govengers/livewire"
	"github.com/govengers/livewire/query"
)

type todo struct {
	ID        uuid.UUID `json:"id"`
	Title     string    `json:"title"`
	Done      bool      `json:"done"`
	CreatedAt time.Time `json:"createdAt"`
}

type createTodo struct {
	ID    *uuid.UUID `json:"id,omitempty"`
	Title string     `json:"title"`
}

func main() {
	registry, err := livewire.NewRegistry(&livewire.RegistryOptions{BasePath: "/api/v1"})
	if err != nil {
		fmt.Println(err)
		return
	}
	err = registry.Add(
		livewire.NewResource("todos", "/todos", &livewire.ResourceOptions[todo]{
			Tables: []string{"todos"},
			Read:   authorization.IsUser(),
			Fields: query.Fields{
				{Name: "id", Type: query.TypeUUID, SQL: "todos.id", Filter: true, Sort: true},
				{Name: "title", Type: query.TypeText, SQL: "todos.title", Filter: true, Sort: true, Search: true},
				{Name: "done", Type: query.TypeBoolean, SQL: "todos.done", Filter: true, Sort: true},
				{Name: "createdAt", Type: query.TypeTime, SQL: "todos.created_at", Filter: true, Sort: true},
			},
			DefaultSort: []query.SortTerm{{Field: "createdAt", Descending: true}},
			Item:        &livewire.ItemKey{Parameter: "id", Field: "id"},
			List: func(context.Context, *query.ListQuery) (*livewire.Page[todo], error) {
				return &livewire.Page[todo]{}, nil // the repository runs postgresadapter.ListPage
			},
			Get: func(context.Context, *query.ListQuery) (*todo, error) {
				return nil, livewire.NotFound()
			},
		}),
		livewire.NewMutation("createTodo", http.MethodPost, "/todos", &livewire.MutationOptions[livewire.NoParameters, createTodo, todo]{
			Check:    authorization.HasPermission("todos", auth.AccessWrite),
			Status:   http.StatusCreated,
			ClientID: livewire.UUIDv7,
			Resource: "todos",
			Effect:   livewire.Upserts("todos"),
			Handle: func(_ context.Context, _ *livewire.NoParameters, body *createTodo) (*todo, error) {
				return &todo{ID: uuid.New(), Title: body.Title}, nil
			},
		}),
	)
	if err != nil {
		fmt.Println(err)
		return
	}
	for _, declaration := range registry.Declarations() {
		fmt.Println(declaration.Kind(), declaration.Name(), declaration.Method(), registry.BasePath()+declaration.Path())
	}
	todos, _ := registry.Lookup("todos")
	fmt.Println(todos.(*livewire.Resource).ItemPath())
}

Output:
resource todos GET /api/v1/todos
mutation createTodo POST /api/v1/todos
/todos/{id}

func (r *Registry) BasePath() string

func (r *Registry) Declarations() []Declaration

func (r *Registry) Lookup(name string) (Declaration, bool)

func (r *Registry) Observe(ctx context.Context, outcome Outcome)

func (r *Registry) Tenant(ctx context.Context, parameters any) (string, error)

type RegistryOptions ¶

type RegistryOptions struct {
	BasePath string
	Tenant   func(ctx context.Context, parameters any) (string, error)
	Observer Observer
}

RegistryOptions configures the registry. BasePath is the prefix of every REST route ("/api/v1"; empty for none) and must start with a slash and not end with one. Tenant resolves the tenant of a request from the decoded parameters (a *Parameters, nil for a resource read) and the identity in ctx (D42); nil means one tenant. Observer receives the outcomes of the engine and the adapters; nil means none.

type RequestFrame ¶

type RequestFrame struct {
	ID             string            `json:"id"`
	Operation      Operation         `json:"op"`
	Target         string            `json:"target,omitempty"`
	Parameters     map[string]string `json:"params,omitempty"`
	Body           json.RawMessage   `json:"body,omitempty"`
	IdempotencyKey string            `json:"idempotencyKey,omitempty"`
}

RequestFrame is one client request on the socket. Target names the declaration of a read with the read kind after a dot ("parts", "parts.item", "parts.distinct", "parts.presence"; ReadKind), the mutation of a call, the declaration of a join or leave, and the subscription of an unsubscribe. Parameters are the target's parameters by name as a REST query string would carry them (a list parameter is one comma-separated value); Body is the mutation body of a call, the calls of a batch (a JSON array of BatchCall) or the state of a join; IdempotencyKey is the Idempotency-Key of a call or batch (D16).

type Resource ¶

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

Resource is a filterable list of items with optional item, distinct and history reads and an export. Its routes are GET Path (list), GET ItemPath (one item), GET DistinctPath (distinct values), GET HistoryPath (one item's versions) and GET ExportPath (every row as CSV); all take the reserved parameters.

func NewResource[Item any](name, path string, options *ResourceOptions[Item]) *Resource

package main

import (
	"context"
	"encoding/json"
	"fmt"
	"net/http"

	"github.com/google/uuid"
	"github.com/govengers/auth"
	"github.com/govengers/auth/authorization"

	"github.com/govengers/livewire"
	"github.com/govengers/livewire/query"
)

type employee struct {
	ID     uuid.UUID `json:"id"`
	Name   string    `json:"name"`
	Salary int       `json:"salary"`
}

type employeeParameters struct {
	ID uuid.UUID `path:"id"`
}

type updateEmployee struct {
	Salary *int    `json:"salary,omitempty"`
	Note   *string `json:"note,omitempty"`
}

func listEmployees(context.Context, *query.ListQuery) (*livewire.Page[employee], error) {
	return &livewire.Page[employee]{}, nil
}

func listPayroll(context.Context, *livewire.NoParameters) ([]employee, error) {
	return nil, nil
}

func saveEmployee(context.Context, *employeeParameters, *updateEmployee) (*employee, error) {
	return nil, livewire.NotFound()
}

func main() {
	// snippet:begin column-checks
	staff := authorization.HasRole("staff")
	employees := livewire.NewResource("employees", "/employees", &livewire.ResourceOptions[employee]{
		Tables: []string{"employees"},
		Read:   authorization.IsUser(),
		Fields: query.Fields{
			{Name: "id", Type: query.TypeUUID, SQL: "employees.id", Filter: true, Sort: true},
			{Name: "name", Type: query.TypeText, SQL: "employees.name", Filter: true, Sort: true, Search: true},
			{Name: "salary", Type: query.TypeInteger, SQL: "employees.salary", Filter: true, Sort: true, Read: staff},
		},
		DefaultSort: []query.SortTerm{{Field: "name"}},
		Cursor:      true, // keyset pages: the `after` parameter and ListResponse.next (D38)
		List:        listEmployees,
	})
	payroll := livewire.NewList("payroll", "/payroll", &livewire.ListOptions[employee, livewire.NoParameters]{
		Read:    authorization.IsUser(),
		Guarded: []livewire.GuardedField{{Name: "salary", Read: staff}}, // the same for a typed read
		Load:    listPayroll,
	})
	update := livewire.NewMutation("updateEmployee", http.MethodPatch, "/employees/{id}", &livewire.MutationOptions[employeeParameters, updateEmployee, employee]{
		Check:       authorization.IsUser(),
		Resource:    "employees", // "salary" in the body needs the field's Write check, its Read by default
		FieldChecks: map[string]authorization.Check{"note": authorization.HasRole("manager")},
		Handle:      saveEmployee,
	})
	// snippet:end column-checks
	registry, err := livewire.NewRegistry(nil)
	if err != nil {
		fmt.Println(err)
		return
	}
	if err := registry.Add(employees, payroll, update); err != nil {
		fmt.Println(err)
		return
	}
	ada := auth.WithIdentity(context.Background(), &auth.Identity{Provider: "example", Subject: "ada", Active: true})
	visible, err := livewire.RedactItems(ada, employees.Fields(), json.RawMessage(`[{"id":"0190e3c8-0000-7000-8000-000000000001","name":"Grace","salary":100}]`))
	if err != nil {
		fmt.Println(err)
		return
	}
	fmt.Println(string(visible))
}

Output:
[{"id":"0190e3c8-0000-7000-8000-000000000001","name":"Grace"}]

func (s *Resource) Check() authorization.Check

func (r *Resource) Cursor() bool

func (s *Resource) DecodeParameters(source ParameterSource) (any, error)

func (r *Resource) DefaultSort() []query.SortTerm

func (r *Resource) DistinctPath() string

func (r *Resource) DistinctQuery(ctx context.Context, parameters *ReadParameters) (*query.ListQuery, query.Field, error)

func (r *Resource) ExportColumns() []string

func (r *Resource) ExportPath() string

func (r *Resource) Fields() query.Fields

func (r *Resource) HistoryPath() string

func (r *Resource) Item() *ItemKey

func (r *Resource) ItemPath() string

func (r *Resource) ItemQuery(ctx context.Context, source ParameterSource) (*query.ListQuery, error)

func (r *Resource) ItemType() reflect.Type

func (r *Resource) Kind() Kind

func (r *Resource) ListQuery(ctx context.Context, parameters *ReadParameters) (*query.ListQuery, error)

func (r *Resource) LoadDistinct(ctx context.Context, field string, listQuery *query.ListQuery) ([]DistinctValue, error)

func (r *Resource) LoadItem(ctx context.Context, listQuery *query.ListQuery) (any, error)

func (r *Resource) LoadList(ctx context.Context, listQuery *query.ListQuery) (any, error)

func (s *Resource) Method() string

func (s *Resource) Name() string

func (s *Resource) Parameters() []Parameter

func (l *Resource) Partition() PartitionResolver

func (s *Resource) Path() string

func (r *Resource) PresencePath() string

func (s *Resource) Tables() []string

func (r *Resource) Versioned() bool

type ResourceOptions ¶

type ResourceOptions[Item any] struct {
	Tables          []string
	Read            authorization.Check
	Partition       PartitionResolver
	Fields          query.Fields
	DefaultSort     []query.SortTerm
	Scope           func(ctx context.Context) (query.Predicate, error)
	MaximumLimit    int
	CountCap        int
	DistinctMaximum int
	Item            *ItemKey
	Versioned       bool
	ExportColumns   []string
	Cursor          bool
	List            func(ctx context.Context, listQuery *query.ListQuery) (*Page[Item], error)
	Get             func(ctx context.Context, listQuery *query.ListQuery) (*Item, error)
	Distinct        func(ctx context.Context, field string, listQuery *query.ListQuery) ([]DistinctValue, error)
	History         func(ctx context.Context, listQuery *query.ListQuery) (*Page[Version[Item]], error)
	Export          func(ctx context.Context, listQuery *query.ListQuery, columns query.Fields, writer io.Writer) (int, error)
}

ResourceOptions declares a filterable resource (D11). Read and List are required; Fields must validate (query.Fields.Validate) and a field left Nullable false is derived from the item type: a pointer field of the item is nullable. Get is required with Item and refused without it. Scope narrows every read and re-run before filter and count; nil is no scope. MaximumLimit clamps the page (default 100), CountCap caps the total (0 counts every row), DistinctMaximum caps a distinct read (default 1000). Cursor allows keyset pagination with the `after` parameter and answers the Next of List's Page as ListResponse.next (D38, D55). Versioned marks the item as carrying `version` (D34); History, which needs Versioned and the Item key on the uuid field "id" (its SQL the table's id column), reads one item's versions for the history route: its query is the reserved filter, sort and page over HistoryFields, scoped to the history table's `id = key`, and the subscription of it re-runs on the resource's Tables, which every version is written with. Export streams every row under scope, filter and sort to the writer for the export route (D35) and returns how many it wrote: the columns are ExportColumns, or every field, without those whose Read check refuses the caller, and a repository passes them to postgresadapter.WriteCSV, which writes a text a spreadsheet would run as a formula with a single quote in front (D69). Partition names a subscription's partition (D25); nil means the tenant.

type ResponseFrame ¶

type ResponseFrame struct {
	ID           string          `json:"id"`
	OK           bool            `json:"ok"`
	Status       int             `json:"status"`
	Payload      json.RawMessage `json:"payload,omitempty"`
	Error        *ErrorBody      `json:"error,omitempty"`
	Subscription string          `json:"subscription,omitempty"`
	FilterID     string          `json:"filterId,omitempty"`
}

ResponseFrame answers one request by its ID. Status is the HTTP status the same request gets on REST; Payload is byte-for-byte the REST body on success, Error the body of a refusal. Subscription names the subscription a subscribe opened, FilterID the stored filter an inline filter was registered as (D13).

type StoredFilter ¶

type StoredFilter struct {
	ID         string
	Owner      Owner
	Resource   string
	Context    string
	Name       string
	Document   json.RawMessage
	Hash       string
	CreatedAt  time.Time
	LastUsedAt time.Time
}

StoredFilter is a filter document a client stored for a resource (D13). Context is the app's dimension of the dedup key (a view or page name, "" for none); Name is empty for an unnamed filter, which is swept after 30 days without use; Hash is query.Hash of Document. Dedup is per owner, resource, context and hash.

type Transaction ¶

type Transaction interface {
	Commit(ctx context.Context) error
	Rollback(ctx context.Context) error
	Handle() any
}

Transaction is an engine transaction (D31, D42, D45) as the core sees it. Only the engine holds it: exactly one of Commit and Rollback is called, once. Handle is the query-only value the engine puts into the unit of work's context (WithTransaction): a value that can run statements in the transaction but has no Commit or Rollback (postgresadapter hands out sqlc's DBTX method set, never the pgx.Tx), so a handler or loader cannot end the engine's transaction.

type TransactionDetails ¶

type TransactionDetails struct {
	Tenant     string
	Identity   *auth.Identity
	Mutation   string
	Parameters any
	RequestID  string
	ReadOnly   bool
}

TransactionDetails is what a transaction records for the triggers and policies (D31, D32, D42): the tenant (SET LOCAL livewire.tenant, "" with a single tenant), the effective identity (its Real() is the real actor), the mutation's name and decoded parameters and the request id (SET LOCAL livewire.actor). ReadOnly marks the REPEATABLE READ READ ONLY transaction of a read (D45: every engine unit of work has one): it carries the tenant and no actor; Mutation is empty then and for a batch's outer transaction.

type Transactor ¶

type Transactor interface {
	Begin(ctx context.Context, transactionDetails TransactionDetails) (Transaction, error)
}

Transactor begins an engine transaction (D31, D42). The implementation sets the tenant and, for a write, the actor of transactionDetails (SET LOCAL) before it returns, so triggers and Row Level Security policies see them.

type Upload ¶

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

Upload is a binary write: REST only, POST, multipart or raw body, declared content types and size limit, typed parameters, JSON response.

func NewUpload[Parameters, Response any](name, path string, options *UploadOptions[Parameters, Response]) *Upload

func (u *Upload) Accepts(contentType string) string

func (s *Upload) Check() authorization.Check

func (u *Upload) ContentTypes() []string

func (s *Upload) DecodeParameters(source ParameterSource) (any, error)

func (u *Upload) Handle(ctx context.Context, parameters any, file *File) (any, error)

func (u *Upload) Kind() Kind

func (u *Upload) MaximumBytes() int64

func (s *Upload) Method() string

func (s *Upload) Name() string

func (s *Upload) Parameters() []Parameter

func (u *Upload) ParametersType() reflect.Type

func (s *Upload) Path() string

func (u *Upload) ResponseType() reflect.Type

func (u *Upload) Status() int

func (s *Upload) Tables() []string

type UploadOptions ¶

type UploadOptions[Parameters, Response any] struct {
	Check        authorization.Check
	Status       int
	ContentTypes []string
	MaximumBytes int64
	Handle       func(ctx context.Context, parameters *Parameters, file *File) (*Response, error)
}

UploadOptions declares a binary write (D17). Check, ContentTypes, MaximumBytes and Handle are required; Status is the success status (default 200).

type UploadRequest ¶

type UploadRequest struct {
	Target         string
	Source         ParameterSource
	File           *File
	IdempotencyKey string
	RequestID      string
}

UploadRequest is one upload as the REST adapter hands it to Engine.Upload: the upload's name, the parameters, the file it read (content type, size and body) and, as for a call, the Idempotency-Key and the request id.

type Version ¶

type Version[Item any] struct {
	ID        int             `json:"id"`
	Operation ChangeOperation `json:"operation"`
	ValidFrom time.Time       `json:"validFrom"`
	ValidTo   *time.Time      `json:"validTo"`
	Actor     string          `json:"actor"`
	RealActor string          `json:"realActor"`
	Mutation  string          `json:"mutation"`
	RequestID string          `json:"requestId"`
	Data      *Item           `json:"data"`
}

Version is one version of an item of a versioned resource as its history read answers it (D34), one row of postgresadapter.HistorySQL's `<table>_history`: ID is the version number (1, 2, ... per item), the key a live history is diffed by; Operation is what the write did; ValidFrom and ValidTo bound the time the version was current (ValidTo nil for the current one; a delete is a closed version of the last row); Actor, RealActor, Mutation and RequestID are what the engine's transaction recorded (D31; empty outside one); Data is the item as the version left it, in the item's JSON shape: the loader maps the stored row to it. Data passes the resource's column checks like every item (D39).