plug

package
v0.31.0 Latest Latest
Warning

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

 Go to latest Published: Oct 17, 2026 License: MIT Imports: 9 Imported by: 0

README

plug

import "github.com/kitsunium/sdk/framework/internal/kit/plug"

Package plug is where kit's opt-in subsystems plug in: the HTTP engine, the frontends' file server and the process sampler of the runtime graph (framework/kit/server), the Studio's event stream and its profiler (framework/kit/studio). kit reads what they registered through the hooks declared here, and imports none of the SDK packages behind them: a product that does not import a subsystem neither links nor initialises its packages.

It is also the contract between kit's core and the subsystems ADR 0179 takes out of it, as database/sql/driver is between database/sql and a driver: the store subsystem's engine over documents, its siblings and kit's scope on a database (Stores), which framework/kit/store will set. Until it exists the core runs the stores itself; the start refuses a declaration whose subsystem the program does not link.

The package imports the standard library and the framework's model only, so that kit and every subsystem can import it.

Index

Constants

const LabelLoop string = "kit_loop"

LabelLoop is the pprof label naming the loop a goroutine belongs to.

const LabelNode string = "kit_node"

LabelNode is the pprof label naming the node a goroutine works for.

const WriteInsert WriteMode = 1

WriteInsert expects nothing under the key, and is refused otherwise.

const WriteReplace WriteMode = 2

WriteReplace expects a document under the key, and is refused otherwise: never a resurrection.

const WriteUpsert WriteMode = 0

WriteUpsert writes whatever the key holds: a creation or a replacement.

Variables

var NewHTTPServer atomic.Pointer[func(cfg HTTPConfig) HTTPServer]

NewHTTPServer builds the HTTP engine an app in the server profile serves on; nil until framework/kit/server is imported.

var NewStaticFiles atomic.Pointer[func(fsys fs.FS, csp string) (http.Handler, error)]

NewStaticFiles builds the file server of a frontend's tree; nil until framework/kit/server is imported.

var OpenEventStream atomic.Pointer[func(w http.ResponseWriter, r *http.Request) (EventStream, error)]

OpenEventStream opens a Server-Sent Events stream on w; nil until framework/kit/studio is imported.

var SampleProcess atomic.Pointer[func() *model.Process]

SampleProcess samples the running process — its heap, goroutines, collections and CPU time — for the runtime graph a serving app answers; nil until framework/kit/server is imported, and the graph then carries no process (ADR 0172).

var Stores atomic.Pointer[StoreDriverConfig]

Stores is the store subsystem: the engines kit's stores run on and kit's scope on a database; nil until framework/kit/store is imported. Until that package exists (ADR 0179, step 3) the core runs the stores itself and nothing sets it; once it does, a product that declares a store or a database without it is refused at the start (ADR 0179 §6).

var StudioProfiler atomic.Pointer[ProfilerConfig]

StudioProfiler is the Studio's profiler; nil until framework/kit/studio is imported.

type Database

Database is kit's scope on one database (ADR 0179 §2): the transactions kit.Transact opens on it, their savepoints, and the functions held until their end. The core knows a database only through it; the store package implements it over the SDK's sql.

type Database interface {
	// Defer holds fn until the transaction ctx carries for the database
	// commits, and reports true; outside one it holds nothing and reports
	// false.
	Defer(ctx context.Context, fn func()) bool
	// InTransaction reports whether ctx carries a transaction of this
	// database.
	InTransaction(ctx context.Context) bool
	// OnAbort holds fn until the work of the scope ctx carries for the
	// database is undone, and reports true; outside one it holds nothing
	// and reports false.
	OnAbort(ctx context.Context, fn func(ctx context.Context)) bool
	// Transact runs fn in a transaction of the database, or in a savepoint
	// of the one ctx carries for it: nil commits or releases, an error
	// rolls back.
	Transact(ctx context.Context, fn func(ctx context.Context) error) error
}

func (Database) Defer
func (Database) Defer(ctx context.Context, fn func()) bool

Defer holds fn until the transaction ctx carries for the database commits, and reports true; outside one it holds nothing and reports false.

func (Database) InTransaction
func (Database) InTransaction(ctx context.Context) bool

InTransaction reports whether ctx carries a transaction of this database.

func (Database) OnAbort
func (Database) OnAbort(ctx context.Context, fn func(ctx context.Context)) bool

OnAbort holds fn until the work of the scope ctx carries for the database is undone, and reports true; outside one it holds nothing and reports false.

func (Database) Transact
func (Database) Transact(ctx context.Context, fn func(ctx context.Context) error) error

Transact runs fn in a transaction of the database, or in a savepoint of the one ctx carries for it: nil commits or releases, an error rolls back.

type DatabaseConfig

DatabaseConfig is one database a product declares, as kit opened it: its pool, its dialect and the timeout of each call.

type DatabaseConfig struct {
	// Name is the database's, as the product declared it.
	Name    string
	// DB is the pool kit.Engine opened.
	DB      *sql.DB
	// Dialect is the engine's SQL dialect: "postgres", "mysql" or
	// "sqlite".
	Dialect string
	// Timeout bounds each call kit makes on the database.
	Timeout time.Duration
}

type DocumentValue

DocumentValue is a record as a store's engine holds it (ADR 0179 §2): its JSON as it rests, byte for byte what kit encodes, and the entity once decoded, kept beside it so that a read, an index or a privacy walk does not decode it twice.

type DocumentValue struct {
	// JSON is the record as it rests.
	JSON  json.RawMessage
	// Value is the entity decoded from JSON, nil until something decoded it;
	// the store's typed facade asserts it to its type.
	Value any
}

type EventStream

EventStream is one Server-Sent Events stream: the Studio's live events.

type EventStream interface {
	// Close ends the stream.
	Close() error
	// Done is closed when the client left.
	Done() <-chan struct{}
	// Send writes one event's data.
	Send(data string) error
}

func (EventStream) Close
func (EventStream) Close() error

Close ends the stream.

func (EventStream) Done
func (EventStream) Done() <-chan struct{}

Done is closed when the client left.

func (EventStream) Send
func (EventStream) Send(data string) error

Send writes one event's data.

type Folder

Folder is an engine that keeps what its writes left beside its data, and can fold it in now. A sibling of StoreEngine.

type Folder interface {
	// Fold rewrites the store's data with only what it holds now.
	Fold(ctx context.Context) error
}

func (Folder) Fold
func (Folder) Fold(ctx context.Context) error

Fold rewrites the store's data with only what it holds now.

type HTTPConfig

HTTPConfig is what kit asks of the HTTP engine: where to listen, its one socket, its bounds, and the handler.

type HTTPConfig struct {
	// Addr is where to listen, "host:port".
	Addr           string
	// Shards is how many sockets the engine opens on Addr.
	Shards         int
	// ReadHeader, Read, Write and Idle bound a request's phases.
	ReadHeader     time.Duration
	// ReadHeader, Read, Write and Idle bound a request's phases.
	Read           time.Duration
	// ReadHeader, Read, Write and Idle bound a request's phases.
	Write          time.Duration
	// ReadHeader, Read, Write and Idle bound a request's phases.
	Idle           time.Duration
	// MaxHeaderBytes bounds a request's header.
	MaxHeaderBytes int
	// Handler answers every request.
	Handler        http.Handler
}

type HTTPServer

HTTPServer is the HTTP engine kit starts, reads and stops.

type HTTPServer interface {
	// Shutdown drains the engine within ctx.
	Shutdown(ctx context.Context) error
	// Start binds the address and serves, returning once bound.
	Start(ctx context.Context) error
	// State says what the engine binds and serves.
	State() HTTPState
}

func (HTTPServer) Shutdown
func (HTTPServer) Shutdown(ctx context.Context) error

Shutdown drains the engine within ctx.

func (HTTPServer) Start
func (HTTPServer) Start(ctx context.Context) error

Start binds the address and serves, returning once bound.

func (HTTPServer) State
func (HTTPServer) State() HTTPState

State says what the engine binds and serves.

type HTTPState

HTTPState is what the HTTP engine says of itself once it runs: the address it bound, and its connections.

type HTTPState struct {
	// Addr is the address the engine bound, "" before it did.
	Addr      string
	// Listeners is how many sockets it listens on.
	Listeners int
	// Active are the connections being served, Total those accepted since
	// the start, Rejected those refused.
	Active    int64
	Total     uint64
	Rejected  uint64
}

type IndexSpec

IndexSpec declares one secondary index of a store, over documents: the product's index function on its type, wrapped once at the declaration.

type IndexSpec struct {
	// Name reads the index, and names it in a refusal.
	Name   string
	// Unique refuses a write that would file two documents under one key.
	Unique bool
	// Keys are a document's keys in the index; an empty key is not indexed.
	Keys   func(d DocumentValue) []string
}

type Keyser

Keyser is an engine that lists the keys of its documents, in key order, above after, without reading a document. A sibling of StoreEngine.

type Keyser interface {
	// Keys yields the keys above after, in order, then its failure if any.
	Keys(ctx context.Context, after string) iter.Seq2[string, error]
}

func (Keyser) Keys
func (Keyser) Keys(ctx context.Context, after string) iter.Seq2[string, error]

Keys yields the keys above after, in order, then its failure if any.

type ProfilerConfig

ProfilerConfig is the Studio's profiler: the live heap folded onto the graph's nodes, and every goroutine grouped.

type ProfilerConfig struct {
	// Heap folds the live heap onto g's nodes; source says where a function
	// of a module lies, nil when it knows none.
	Heap       func(g *model.Graph, source SourceFunc) (*model.Profile, error)
	// Goroutines groups every goroutine of the process, read at at.
	Goroutines func(at time.Time) (*model.Goroutines, error)
}

type SourceFunc

SourceFunc says where the function fn, at file:line, lies in the product, nil when it knows none.

type SourceFunc func(file string, line int, fn string) *model.Source

type StoreConfig

StoreConfig is what kit asks of one store's engine: the store, its key and its indexes over documents, where it rests and what it keeps.

type StoreConfig struct {
	// Name is the store's, as its files and its table name it.
	Name     string
	// Key is a document's key: the product's key function on its type,
	// wrapped once at the declaration.
	Key      func(d DocumentValue) string
	// Decode is the entity a document's JSON holds, which the engine keeps
	// as the document's Value.
	Decode   func(raw json.RawMessage) (any, error)
	// Indexes are the store's secondary indexes.
	Indexes  []IndexSpec
	// Data is the data directory the store rests in — the SDK's writable
	// file system, which the engine asserts — and Path its snapshot there;
	// a nil Data and a nil Database keep the store in memory.
	Data     fs.FS
	// Path is the store's snapshot in Data.
	Path     string
	// Database keeps the store, nil when the data directory or memory does.
	Database Database
	// Versions is how many former versions of each record the engine keeps,
	// none when zero; Clock stamps them.
	Versions int
	// Clock is the app's clock, which stamps a version.
	Clock    func() time.Time
	// Held reports whether a record's versions are held, and no write may
	// prune them.
	Held     func(key string) bool
}

type StoreDriverConfig

StoreDriverConfig is what framework/kit/store plugs into kit: how a store's engine opens, and how kit opens its scope on a database.

type StoreDriverConfig struct {
	// Open opens the engine of one store, as cfg places it: loaded from the
	// data directory, empty in memory, or on a database.
	Open     func(cfg StoreConfig) (StoreEngine, error)
	// Database opens kit's scope on one database's pool.
	Database func(cfg DatabaseConfig) (Database, error)
}

type StoreEngine

StoreEngine is what a store runs on, over documents (ADR 0179 §2): the non-generic engine under Store[T]. Its refusals are kit's: the engine translates the SDK's before they reach the core. Every call takes the caller's context, which carries the transaction the call joins. It grows by the sibling interfaces below, never by a method (the SDK's ADR 0039).

type StoreEngine interface {
	// Close releases the engine.
	Close() error
	// Count says how many documents the store holds.
	Count(ctx context.Context) (int, error)
	// Delete removes the document under key.
	Delete(ctx context.Context, key string) error
	// Entries returns up to limit documents as they rest, in key order.
	Entries(ctx context.Context, limit int) ([]json.RawMessage, error)
	// Filter returns the documents keep accepts, in key order.
	Filter(ctx context.Context, keep func(d DocumentValue) bool) ([]DocumentValue, error)
	// Find returns the documents an index files under key, in key order.
	Find(ctx context.Context, index string, key string) ([]DocumentValue, error)
	// Get returns the document under key.
	Get(ctx context.Context, key string) (DocumentValue, error)
	// List returns every document, in key order.
	List(ctx context.Context) ([]DocumentValue, error)
	// Lookup returns the document a unique index files under key.
	Lookup(ctx context.Context, index string, key string) (DocumentValue, error)
	// Update applies fn to the document under key and stores the result,
	// atomically with respect to every other write of the store.
	Update(ctx context.Context, key string, fn func(d *DocumentValue) error) (DocumentValue, error)
	// Watch registers the functions told the key of every document written
	// and deleted, once the write stands.
	Watch(onWrite func(key string), onDelete func(key string))
	// Write stores d as mode says. The document and its index keys are kept
	// together, or neither.
	Write(ctx context.Context, d DocumentValue, mode WriteMode) error
}

func (StoreEngine) Close
func (StoreEngine) Close() error

Close releases the engine.

func (StoreEngine) Count
func (StoreEngine) Count(ctx context.Context) (int, error)

Count says how many documents the store holds.

func (StoreEngine) Delete
func (StoreEngine) Delete(ctx context.Context, key string) error

Delete removes the document under key.

func (StoreEngine) Entries
func (StoreEngine) Entries(ctx context.Context, limit int) ([]json.RawMessage, error)

Entries returns up to limit documents as they rest, in key order.

func (StoreEngine) Filter
func (StoreEngine) Filter(ctx context.Context, keep func(d DocumentValue) bool) ([]DocumentValue, error)

Filter returns the documents keep accepts, in key order.

func (StoreEngine) Find
func (StoreEngine) Find(ctx context.Context, index string, key string) ([]DocumentValue, error)

Find returns the documents an index files under key, in key order.

func (StoreEngine) Get
func (StoreEngine) Get(ctx context.Context, key string) (DocumentValue, error)

Get returns the document under key.

func (StoreEngine) List
func (StoreEngine) List(ctx context.Context) ([]DocumentValue, error)

List returns every document, in key order.

func (StoreEngine) Lookup
func (StoreEngine) Lookup(ctx context.Context, index string, key string) (DocumentValue, error)

Lookup returns the document a unique index files under key.

func (StoreEngine) Update
func (StoreEngine) Update(ctx context.Context, key string, fn func(d *DocumentValue) error) (DocumentValue, error)

Update applies fn to the document under key and stores the result, atomically with respect to every other write of the store.

func (StoreEngine) Watch
func (StoreEngine) Watch(onWrite func(key string), onDelete func(key string))

Watch registers the functions told the key of every document written and deleted, once the write stands.

func (StoreEngine) Write
func (StoreEngine) Write(ctx context.Context, d DocumentValue, mode WriteMode) error

Write stores d as mode says. The document and its index keys are kept together, or neither.

type TombstoneValue

TombstoneValue is one record in a store's trash: its key, and when it was trashed.

type TombstoneValue struct {
	// Key is the trashed record's key.
	Key string
	// At is when the record was trashed, in UTC.
	At  time.Time
}

type Trasher

Trasher is an engine that keeps a trash. A sibling of StoreEngine.

type Trasher interface {
	// Purge empties the trash of the record trashed under key, its versions
	// with it.
	Purge(ctx context.Context, key string) error
	// Tombstones are every record in the trash, in key order.
	Tombstones(ctx context.Context) ([]TombstoneValue, error)
	// Trash moves the record under key to the trash: gone from every read,
	// its index keys freed, its versions kept.
	Trash(ctx context.Context, key string) error
	// Untrash brings the record trashed under key back as it was.
	Untrash(ctx context.Context, key string) error
}

func (Trasher) Purge
func (Trasher) Purge(ctx context.Context, key string) error

Purge empties the trash of the record trashed under key, its versions with it.

func (Trasher) Tombstones
func (Trasher) Tombstones(ctx context.Context) ([]TombstoneValue, error)

Tombstones are every record in the trash, in key order.

func (Trasher) Trash
func (Trasher) Trash(ctx context.Context, key string) error

Trash moves the record under key to the trash: gone from every read, its index keys freed, its versions kept.

func (Trasher) Untrash
func (Trasher) Untrash(ctx context.Context, key string) error

Untrash brings the record trashed under key back as it was.

type VersionKeeper

VersionKeeper is an engine that keeps its records' versions. A sibling of StoreEngine.

type VersionKeeper interface {
	// RewriteVersions rewrites the former versions of the record under key
	// as fn returns them: fn may drop a version or change what one holds,
	// never add or renumber one.
	RewriteVersions(ctx context.Context, key string, fn func(vs []VersionValue) ([]VersionValue, error)) error
	// StoredVersions are the versions of the record under key, newest
	// first, the current one first.
	StoredVersions(ctx context.Context, key string) ([]VersionValue, error)
}

func (VersionKeeper) RewriteVersions
func (VersionKeeper) RewriteVersions(ctx context.Context, key string, fn func(vs []VersionValue) ([]VersionValue, error)) error

RewriteVersions rewrites the former versions of the record under key as fn returns them: fn may drop a version or change what one holds, never add or renumber one.

func (VersionKeeper) StoredVersions
func (VersionKeeper) StoredVersions(ctx context.Context, key string) ([]VersionValue, error)

StoredVersions are the versions of the record under key, newest first, the current one first.

type VersionValue

VersionValue is one version of a record: its number, when the write that made it ran, what that write said about it, and the record as it held it.

type VersionValue struct {
	// Number counts a record's versions from 1.
	Number uint64
	// At is when the write that made the version ran, in UTC.
	At     time.Time
	// Meta is what the write said about it: who made it, which command.
	Meta   map[string]string
	// JSON is the record as the version holds it.
	JSON   json.RawMessage
}

type VersionWeightValue

VersionWeightValue is what a store keeps beyond the records it holds: its former versions and its trash, counted and weighed.

type VersionWeightValue struct {
	// Former is how many former versions the store keeps.
	Former  int
	// Trashed is how many records are in the trash.
	Trashed int
	// Bytes is what the former versions and the trashed records weigh.
	Bytes   int64
}

type VersionWeighter

VersionWeighter is an engine that says what its records' versions weigh. A sibling of StoreEngine.

type VersionWeighter interface {
	// VersionWeight is what the store's versions and trash weigh.
	VersionWeight(ctx context.Context) (VersionWeightValue, error)
}

func (VersionWeighter) VersionWeight
func (VersionWeighter) VersionWeight(ctx context.Context) (VersionWeightValue, error)

VersionWeight is what the store's versions and trash weigh.

type WriteMode

WriteMode says what a write expects to find under the document's key.

type WriteMode int

Generated from docs/api by tools/genindex.

Documentation

Overview

Package plug is where kit's opt-in subsystems plug in: the HTTP engine, the frontends' file server and the process sampler of the runtime graph (framework/kit/server), the Studio's event stream and its profiler (framework/kit/studio). kit reads what they registered through the hooks declared here, and imports none of the SDK packages behind them: a product that does not import a subsystem neither links nor initialises its packages.

It is also the contract between kit's core and the subsystems ADR 0179 takes out of it, as database/sql/driver is between database/sql and a driver: the store subsystem's engine over documents, its siblings and kit's scope on a database (Stores), which framework/kit/store will set. Until it exists the core runs the stores itself; the start refuses a declaration whose subsystem the program does not link.

The package imports the standard library and the framework's model only, so that kit and every subsystem can import it.

Index

Constants

View Source 
const (
	// LabelNode is the pprof label naming the node a goroutine works for.
	LabelNode string = "kit_node"
	// LabelLoop is the pprof label naming the loop a goroutine belongs to.
	LabelLoop string = "kit_loop"
)

Variables

View Source 
var (
	// NewHTTPServer builds the HTTP engine an app in the server profile
	// serves on; nil until framework/kit/server is imported.
	NewHTTPServer atomic.Pointer[func(cfg HTTPConfig) HTTPServer]
	// NewStaticFiles builds the file server of a frontend's tree; nil until
	// framework/kit/server is imported.
	NewStaticFiles atomic.Pointer[func(fsys fs.FS, csp string) (http.Handler, error)]
	// SampleProcess samples the running process — its heap, goroutines,
	// collections and CPU time — for the runtime graph a serving app answers;
	// nil until framework/kit/server is imported, and the graph then carries
	// no process (ADR 0172).
	SampleProcess atomic.Pointer[func() *model.Process]
	// OpenEventStream opens a Server-Sent Events stream on w; nil until
	// framework/kit/studio is imported.
	OpenEventStream atomic.Pointer[func(w http.ResponseWriter, r *http.Request) (EventStream, error)]
	// StudioProfiler is the Studio's profiler; nil until framework/kit/studio
	// is imported.
	StudioProfiler atomic.Pointer[ProfilerConfig]
)
View Source 
var Stores atomic.Pointer[StoreDriverConfig]

Stores is the store subsystem: the engines kit's stores run on and kit's scope on a database; nil until framework/kit/store is imported. Until that package exists (ADR 0179, step 3) the core runs the stores itself and nothing sets it; once it does, a product that declares a store or a database without it is refused at the start (ADR 0179 §6).

Functions

This section is empty.

Types

type Database added in v0.31.0 

type Database interface {
	// Transact runs fn in a transaction of the database, or in a savepoint
	// of the one ctx carries for it: nil commits or releases, an error
	// rolls back.
	Transact(ctx context.Context, fn func(ctx context.Context) error) error
	// InTransaction reports whether ctx carries a transaction of this
	// database.
	InTransaction(ctx context.Context) bool
	// Defer holds fn until the transaction ctx carries for the database
	// commits, and reports true; outside one it holds nothing and reports
	// false.
	Defer(ctx context.Context, fn func()) bool
	// OnAbort holds fn until the work of the scope ctx carries for the
	// database is undone, and reports true; outside one it holds nothing
	// and reports false.
	OnAbort(ctx context.Context, fn func(ctx context.Context)) bool
}

Database is kit's scope on one database (ADR 0179 §2): the transactions kit.Transact opens on it, their savepoints, and the functions held until their end. The core knows a database only through it; the store package implements it over the SDK's sql.

type DatabaseConfig added in v0.31.0 

type DatabaseConfig struct {
	// Name is the database's, as the product declared it.
	Name string
	// DB is the pool kit.Engine opened.
	DB *sql.DB
	// Dialect is the engine's SQL dialect: "postgres", "mysql" or
	// "sqlite".
	Dialect string
	// Timeout bounds each call kit makes on the database.
	Timeout time.Duration
}

DatabaseConfig is one database a product declares, as kit opened it: its pool, its dialect and the timeout of each call.

type DocumentValue added in v0.31.0 

type DocumentValue struct {
	// JSON is the record as it rests.
	JSON json.RawMessage
	// Value is the entity decoded from JSON, nil until something decoded it;
	// the store's typed facade asserts it to its type.
	Value any
}

DocumentValue is a record as a store's engine holds it (ADR 0179 §2): its JSON as it rests, byte for byte what kit encodes, and the entity once decoded, kept beside it so that a read, an index or a privacy walk does not decode it twice.

type EventStream 

type EventStream interface {
	// Send writes one event's data.
	Send(data string) error
	// Done is closed when the client left.
	Done() <-chan struct{}
	// Close ends the stream.
	Close() error
}

EventStream is one Server-Sent Events stream: the Studio's live events.

type Folder added in v0.31.0 

type Folder interface {
	// Fold rewrites the store's data with only what it holds now.
	Fold(ctx context.Context) error
}

Folder is an engine that keeps what its writes left beside its data, and can fold it in now. A sibling of StoreEngine.

type HTTPConfig 

type HTTPConfig struct {
	// Addr is where to listen, "host:port".
	Addr string
	// Shards is how many sockets the engine opens on Addr.
	Shards int
	// ReadHeader, Read, Write and Idle bound a request's phases.
	ReadHeader, Read, Write, Idle time.Duration
	// MaxHeaderBytes bounds a request's header.
	MaxHeaderBytes int
	// Handler answers every request.
	Handler http.Handler
}

HTTPConfig is what kit asks of the HTTP engine: where to listen, its one socket, its bounds, and the handler.

type HTTPServer 

type HTTPServer interface {
	// Start binds the address and serves, returning once bound.
	Start(ctx context.Context) error
	// State says what the engine binds and serves.
	State() HTTPState
	// Shutdown drains the engine within ctx.
	Shutdown(ctx context.Context) error
}

HTTPServer is the HTTP engine kit starts, reads and stops.

type HTTPState 

type HTTPState struct {
	// Addr is the address the engine bound, "" before it did.
	Addr string
	// Listeners is how many sockets it listens on.
	Listeners int
	// Active are the connections being served, Total those accepted since
	// the start, Rejected those refused.
	Active          int64
	Total, Rejected uint64
}

HTTPState is what the HTTP engine says of itself once it runs: the address it bound, and its connections.

type IndexSpec added in v0.31.0 

type IndexSpec struct {
	// Name reads the index, and names it in a refusal.
	Name string
	// Unique refuses a write that would file two documents under one key.
	Unique bool
	// Keys are a document's keys in the index; an empty key is not indexed.
	Keys func(d DocumentValue) []string
}

IndexSpec declares one secondary index of a store, over documents: the product's index function on its type, wrapped once at the declaration.

type Keyser added in v0.31.0 

type Keyser interface {
	// Keys yields the keys above after, in order, then its failure if any.
	Keys(ctx context.Context, after string) iter.Seq2[string, error]
}

Keyser is an engine that lists the keys of its documents, in key order, above after, without reading a document. A sibling of StoreEngine.

type ProfilerConfig 

type ProfilerConfig struct {
	// Heap folds the live heap onto g's nodes; source says where a function
	// of a module lies, nil when it knows none.
	Heap func(g *model.Graph, source SourceFunc) (*model.Profile, error)
	// Goroutines groups every goroutine of the process, read at at.
	Goroutines func(at time.Time) (*model.Goroutines, error)
}

ProfilerConfig is the Studio's profiler: the live heap folded onto the graph's nodes, and every goroutine grouped.

type SourceFunc 

type SourceFunc func(file string, line int, fn string) *model.Source

SourceFunc says where the function fn, at file:line, lies in the product, nil when it knows none.

type StoreConfig added in v0.31.0 

type StoreConfig struct {
	// Name is the store's, as its files and its table name it.
	Name string
	// Key is a document's key: the product's key function on its type,
	// wrapped once at the declaration.
	Key func(d DocumentValue) string
	// Decode is the entity a document's JSON holds, which the engine keeps
	// as the document's Value.
	Decode func(raw json.RawMessage) (any, error)
	// Indexes are the store's secondary indexes.
	Indexes []IndexSpec
	// Data is the data directory the store rests in — the SDK's writable
	// file system, which the engine asserts — and Path its snapshot there;
	// a nil Data and a nil Database keep the store in memory.
	Data fs.FS
	// Path is the store's snapshot in Data.
	Path string
	// Database keeps the store, nil when the data directory or memory does.
	Database Database
	// Versions is how many former versions of each record the engine keeps,
	// none when zero; Clock stamps them.
	Versions int
	// Clock is the app's clock, which stamps a version.
	Clock func() time.Time
	// Held reports whether a record's versions are held, and no write may
	// prune them.
	Held func(key string) bool
}

StoreConfig is what kit asks of one store's engine: the store, its key and its indexes over documents, where it rests and what it keeps.

type StoreDriverConfig added in v0.31.0 

type StoreDriverConfig struct {
	// Open opens the engine of one store, as cfg places it: loaded from the
	// data directory, empty in memory, or on a database.
	Open func(cfg StoreConfig) (StoreEngine, error)
	// Database opens kit's scope on one database's pool.
	Database func(cfg DatabaseConfig) (Database, error)
}

StoreDriverConfig is what framework/kit/store plugs into kit: how a store's engine opens, and how kit opens its scope on a database.

type StoreEngine added in v0.31.0 

type StoreEngine interface {
	// Get returns the document under key.
	Get(ctx context.Context, key string) (DocumentValue, error)
	// List returns every document, in key order.
	List(ctx context.Context) ([]DocumentValue, error)
	// Filter returns the documents keep accepts, in key order.
	Filter(ctx context.Context, keep func(d DocumentValue) bool) ([]DocumentValue, error)
	// Lookup returns the document a unique index files under key.
	Lookup(ctx context.Context, index, key string) (DocumentValue, error)
	// Find returns the documents an index files under key, in key order.
	Find(ctx context.Context, index, key string) ([]DocumentValue, error)
	// Count says how many documents the store holds.
	Count(ctx context.Context) (int, error)
	// Entries returns up to limit documents as they rest, in key order.
	Entries(ctx context.Context, limit int) ([]json.RawMessage, error)
	// Write stores d as mode says. The document and its index keys are kept
	// together, or neither.
	Write(ctx context.Context, d DocumentValue, mode WriteMode) error
	// Update applies fn to the document under key and stores the result,
	// atomically with respect to every other write of the store.
	Update(ctx context.Context, key string, fn func(d *DocumentValue) error) (DocumentValue, error)
	// Delete removes the document under key.
	Delete(ctx context.Context, key string) error
	// Watch registers the functions told the key of every document written
	// and deleted, once the write stands.
	Watch(onWrite, onDelete func(key string))
	// Close releases the engine.
	Close() error
}

StoreEngine is what a store runs on, over documents (ADR 0179 §2): the non-generic engine under Store[T]. Its refusals are kit's: the engine translates the SDK's before they reach the core. Every call takes the caller's context, which carries the transaction the call joins. It grows by the sibling interfaces below, never by a method (the SDK's ADR 0039).

type TombstoneValue added in v0.31.0 

type TombstoneValue struct {
	// Key is the trashed record's key.
	Key string
	// At is when the record was trashed, in UTC.
	At time.Time
}

TombstoneValue is one record in a store's trash: its key, and when it was trashed.

type Trasher added in v0.31.0 

type Trasher interface {
	// Trash moves the record under key to the trash: gone from every read,
	// its index keys freed, its versions kept.
	Trash(ctx context.Context, key string) error
	// Untrash brings the record trashed under key back as it was.
	Untrash(ctx context.Context, key string) error
	// Purge empties the trash of the record trashed under key, its versions
	// with it.
	Purge(ctx context.Context, key string) error
	// Tombstones are every record in the trash, in key order.
	Tombstones(ctx context.Context) ([]TombstoneValue, error)
}

Trasher is an engine that keeps a trash. A sibling of StoreEngine.

type VersionKeeper added in v0.31.0 

type VersionKeeper interface {
	// StoredVersions are the versions of the record under key, newest
	// first, the current one first.
	StoredVersions(ctx context.Context, key string) ([]VersionValue, error)
	// RewriteVersions rewrites the former versions of the record under key
	// as fn returns them: fn may drop a version or change what one holds,
	// never add or renumber one.
	RewriteVersions(ctx context.Context, key string, fn func(vs []VersionValue) ([]VersionValue, error)) error
}

VersionKeeper is an engine that keeps its records' versions. A sibling of StoreEngine.

type VersionValue added in v0.31.0 

type VersionValue struct {
	// Number counts a record's versions from 1.
	Number uint64
	// At is when the write that made the version ran, in UTC.
	At time.Time
	// Meta is what the write said about it: who made it, which command.
	Meta map[string]string
	// JSON is the record as the version holds it.
	JSON json.RawMessage
}

VersionValue is one version of a record: its number, when the write that made it ran, what that write said about it, and the record as it held it.

type VersionWeightValue added in v0.31.0 

type VersionWeightValue struct {
	// Former is how many former versions the store keeps.
	Former int
	// Trashed is how many records are in the trash.
	Trashed int
	// Bytes is what the former versions and the trashed records weigh.
	Bytes int64
}

VersionWeightValue is what a store keeps beyond the records it holds: its former versions and its trash, counted and weighed.

type VersionWeighter added in v0.31.0 

type VersionWeighter interface {
	// VersionWeight is what the store's versions and trash weigh.
	VersionWeight(ctx context.Context) (VersionWeightValue, error)
}

VersionWeighter is an engine that says what its records' versions weigh. A sibling of StoreEngine.

type WriteMode added in v0.31.0 

type WriteMode int

WriteMode says what a write expects to find under the document's key. 

const (
	// WriteUpsert writes whatever the key holds: a creation or a
	// replacement.
	WriteUpsert WriteMode = iota
	// WriteInsert expects nothing under the key, and is refused otherwise.
	WriteInsert
	// WriteReplace expects a document under the key, and is refused
	// otherwise: never a resurrection.
	WriteReplace
)

The write modes.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.