kit

package
v0.26.0 Latest Latest
Warning

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

 Go to latest Published: Oct 15, 2026 License: MIT Imports: 88 Imported by: 0

README

kit

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

Package kit — who may call an operation: the principal, the rules and their checks.

Package kit — activities: what a daemon's idle stop waits for besides its connections, a notion of the product's own — sessions still open, work still queued.

Package kit — the App: the services a product mounts, served by one process.

Package kit — the static analysis a product can be given: the platform's analyzer, run in the background in dev (ADR 0147 §1).

Package kit — process profiles: what an app does with its process (ADR 0147 §5) — serve, run as a daemon, or run one CLI command — and the singleton lock.

Package kit — the architecture the graph draws: where each store keeps its data.

Package kit — authentication: the handler that says who calls, and the user it names.

Package kit — the build a graph describes: the modules and versions it was made of.

Package kit — the catalog of the generic mechanics a node is built from.

Package kit — the kit tag: the classes and words a field of personal data carries.

Package kit — the plan of a Go type's classified members, computed once per type.

Package kit — the walk of a value along its classification plan.

Package kit — the warnings for fields whose name suggests personal data left unclassified.

Package kit — CLI commands: a short command of the product that Main runs once, in the CLI profile, and whose status is the process's.

Package kit — commands: an operation that changes something, with one handler.

Package kit — the app's options and environments.

Package kit — the config command: every setting, its value and where it comes from.

Package kit — the consumer that drains a queue into its handler.

Package kit — the daemon: what a running app knows of itself beyond its nodes.

Package kit — the daemon's HTTP server as the Studio sees it: its loop, its counters, and the middleware every request goes through.

Package kit — the daemon's loops: their states, the scheduler that fires the jobs, and the goroutine labels that name them.

Package kit — databases: the SQL engines a store can be kept on.

Package kit — the start's judgement of the declared databases.

Package kit — the interfaces of databases: the engine a connector gives, and what kit asks of it.

Package kit — the migrations a database runs, and their lock.

Package kit — the placement of each store: which database keeps its data.

Package kit — a database in a running app.

Package kit — the databases as the graph shows them.

Package kit — the decoding of a request into its typed value.

Package kit — the dev tools' routes of the Studio, read-only.

Package kit is the implementation of framework/kit, the framework in which every product is its own diagram. A product imports framework/kit, whose names alias and forward to this package's: here, the types carry the role their name says — StoreService, EndpointService, AppConfigurer — and the facade keeps the names a product writes — Store, Endpoint, AppOption.

Package kit — endpoints: an HTTP route and the operation it serves.

Package kit — the errors a product returns to its callers, and their wire mapping.

Package kit — exposures: an operation an endpoint serves over HTTP.

Package kit — what an exposure takes, and what it exposes.

Package kit — the Go modules of the running binary, read from its build info.

Package kit — the graph: the product as a diagram of what it mounts.

Package kit — history: the former values of the fields that keep them.

Package kit — the history's storage: former values kept beside each record.

Package kit — reading a record's former values.

Package kit — the history as the graph and the Studio show it.

Package kit — what kit's own writes mean to the history.

Package kit — legal holds: records kept whatever their retention says.

Package kit — secondary indexes of a store.

Package kit — the Studio's read API: the graph, the events, the sources.

Package kit — what the source endpoint needs of the root it reads.

Package kit — how the source endpoint opens a file on Unix.

Package kit — how the source endpoint opens a file on Windows: the link itself, never its target.

Package kit — jobs: scheduled work run by the daemon's loop.

Package kit — the privacy journal: what kit did to personal data, and why.

Package kit — idempotency keys and their leases.

Package kit — the compile-time proof of which roles each declaration plays: the interfaces the app reaches its nodes and options through.

Package kit — listeners: inbound ports that are not HTTP, a private socket speaking a versioned contract (ADR 0148).

Package kit — the compile-time proof that a listener is a starter.

Package kit — what a listener needs of the socket it accepts on.

Package kit — the product's logger and the logs the Studio shows.

Package kit — loops: work the daemon waits for, woken by time or by events.

Package kit — mailers: a durable outbox and the transport that empties it.

Package kit — what building an SMTP transport needs of its URL.

Package kit — Main: the whole main function of a product.

Package kit — the migrate command.

Package kit — modules: a set of services a product mounts as one.

Package kit — the start's checks of the modules an app mounts.

Package kit — what a module keeps: its stores and its migrations.

Package kit — the mount of a module: its prefix and its bindings.

Package kit — nodes: what every declaration shares, and its source position.

Package kit — the interfaces of nodes: what every declaration is, and the roles some play.

Package kit — observation: the spans and events of a running product.

Package kit — operations: a typed request answered by a typed response.

Package kit — the password policy of a store's fields.

Package kit — hashing and verifying passwords under their policy.

Package kit — the warnings for endpoints that set passwords outside a policy.

Package kit — ports: an operation a service needs and does not implement.

Package kit — privacy: kit's own service for holds and the journal.

Package kit — erasure: a record's personal data removed as its retention would.

Package kit — export: a person's data as kit gives it back.

Package kit — a store's personal data as the graph shows it.

Package kit — the keys that index personal data without revealing it.

Package kit — the Studio's privacy pages: the journal, the holds, the register.

Package kit — the privacy command.

Package kit — what the privacy command prints.

Package kit — `privacy seal`: a whole store sealed now.

Package kit — the process sample: what the running process uses.

Package kit — the Studio's profiler: the live heap and the goroutines, folded onto the graph.

Package kit — queries: an operation that reads and changes nothing.

Package kit — queued commands: a command run later, from its queue.

Package kit — rate limits on an endpoint, per client.

Package kit — records: the product's data as modules and the Studio reach it.

Package kit — redaction: what a value shows once its secrets are hidden.

Package kit — the register of processing: each store's line.

Package kit — replacements: a test's substitute for an operation.

Package kit — the HTTP request and response an endpoint can reach.

Package kit — retention: how long a store keeps its personal data.

Package kit — the retention of a store in a running app.

Package kit — one pass of retention: what is due is erased or deleted.

Package kit — record revisions: a store's previous versions of each record.

Package kit — what changed between two versions, and a version written back.

Package kit — where a store's versions are kept, engine by engine.

Package kit — what the privacy rules ask of a record's versions.

Package kit — a record's version written back.

Package kit — what the Studio sees of a record's versions.

Package kit — the revisions command: a version of a record written back.

Package kit — binaries and their process roles: one executable, several Apps, and the versioned contracts between them (D22).

Package kit — schemas: the JSON Schema of an operation's types.

Package kit — scopes: the parts of a singleton's lock or of a socket's path that are only known at the start — the user, the executable, a configuration directory —, so one declaration keeps one process per user, per installed copy or per configuration.

Package kit — the current user outside Windows: the process's UID, read from the kernel. os/user would ask libc through cgo — linking the program dynamically — or read /etc/passwd, for a number the kernel gives at once.

Package kit — the current user on Windows: its SID, from os/user, which reads the process token there without cgo.

Package kit — sealing at rest: members sealed where kit keeps them.

Package kit — where the data keys are, against what they seal.

Package kit — cryptographic erasure: a data key destroyed.

Package kit — a document as it lies at rest, sealed member by member.

Package kit — messages at rest: a queue's members sealed.

Package kit — a store that seals: its records as they rest.

Package kit — a store that seals, as kit's port sees it.

Package kit — secrets: the values the product declares and the operator provides.

Package kit — the secrets command.

Package kit — where the secrets are kept, per environment.

Package kit — services: a bounded context and the building blocks it owns.

Package kit — settings: a value the environment gives a service.

Package kit — the interfaces of settings: the values a setting holds, and what kit reads of a declaration.

Package kit — frontends: static assets the product serves.

Package kit — stores: a typed, keyed collection of entities.

Package kit — the engines a store runs on: memory, files or a database.

Package kit — stores on SQL: the SDK's document store over a database.

Package kit — kit's own migrations on a database.

Package kit — telemetry: the numbers a product reports, exported on a private socket when the deployment asks for them (ADR 0149).

Package kit — topics and subscriptions: asynchronous messages of one type.

Package kit — transactions: kit.Transact and its levels.

Package kit — a transaction on a database, the database's own.

Package kit — the data's writer turn, where there are no transactions.

Package kit — a transaction writes one database: the dev warning.

Package kit — watches: how a module hears the writes of a product's marked fields.

Package kit — a watch in a running app: its queue and its consumer.

Package kit — the sentences kit says, in every language it speaks.

Package kit — workflows: a state machine over the entities of one store.

Package kit — the ports the workflow engine reaches a store through.

Index

Constants

const CodeAppConfig errs.Code = 262672

The framework's own failures carry SDK error codes in 0.4.2.* — layer 4 is the framework's, PP 2 this package (ADR 0147 §3) — so a product keeps the whole application range 0x40–0x7F for its own codes. Match them with errs.HasCode. Their Public text is the only part that may reach a caller; none of them is a 4xx, so a caller only ever reads "internal error".

Code 0.4.2.16

const CodeAppListen errs.Code = 262674

The framework's own failures carry SDK error codes in 0.4.2.* — layer 4 is the framework's, PP 2 this package (ADR 0147 §3) — so a product keeps the whole application range 0x40–0x7F for its own codes. Match them with errs.HasCode. Their Public text is the only part that may reach a caller; none of them is a 4xx, so a caller only ever reads "internal error".

Code 0.4.2.18

const CodeAppRunning errs.Code = 262673

The framework's own failures carry SDK error codes in 0.4.2.* — layer 4 is the framework's, PP 2 this package (ADR 0147 §3) — so a product keeps the whole application range 0x40–0x7F for its own codes. Match them with errs.HasCode. Their Public text is the only part that may reach a caller; none of them is a 4xx, so a caller only ever reads "internal error".

Code 0.4.2.17

const CodeCLIFailed errs.Code = 262715

CodeCLIFailed marks the span of a CLI command that exited non-zero.

Code 0.4.2.59

const CodeCatalogue errs.Code = 262712

The framework's own failures carry SDK error codes in 0.4.2.* — layer 4 is the framework's, PP 2 this package (ADR 0147 §3) — so a product keeps the whole application range 0x40–0x7F for its own codes. Match them with errs.HasCode. Their Public text is the only part that may reach a caller; none of them is a 4xx, so a caller only ever reads "internal error".

Code 0.4.2.56

const CodeCommandEncode errs.Code = 262702

The framework's own failures carry SDK error codes in 0.4.2.* — layer 4 is the framework's, PP 2 this package (ADR 0147 §3) — so a product keeps the whole application range 0x40–0x7F for its own codes. Match them with errs.HasCode. Their Public text is the only part that may reach a caller; none of them is a 4xx, so a caller only ever reads "internal error".

Code 0.4.2.46

const CodeCommandKey errs.Code = 262700

The framework's own failures carry SDK error codes in 0.4.2.* — layer 4 is the framework's, PP 2 this package (ADR 0147 §3) — so a product keeps the whole application range 0x40–0x7F for its own codes. Match them with errs.HasCode. Their Public text is the only part that may reach a caller; none of them is a 4xx, so a caller only ever reads "internal error".

Code 0.4.2.44

const CodeCommandQueue errs.Code = 262701

The framework's own failures carry SDK error codes in 0.4.2.* — layer 4 is the framework's, PP 2 this package (ADR 0147 §3) — so a product keeps the whole application range 0x40–0x7F for its own codes. Match them with errs.HasCode. Their Public text is the only part that may reach a caller; none of them is a 4xx, so a caller only ever reads "internal error".

Code 0.4.2.45

const CodeCommandReentrant errs.Code = 262699

Commands and queries.

Code 0.4.2.43

const CodeDatabaseConfig errs.Code = 262690

The framework's own failures carry SDK error codes in 0.4.2.* — layer 4 is the framework's, PP 2 this package (ADR 0147 §3) — so a product keeps the whole application range 0x40–0x7F for its own codes. Match them with errs.HasCode. Their Public text is the only part that may reach a caller; none of them is a 4xx, so a caller only ever reads "internal error".

Code 0.4.2.34

const CodeDatabaseMigrate errs.Code = 262688

The framework's own failures carry SDK error codes in 0.4.2.* — layer 4 is the framework's, PP 2 this package (ADR 0147 §3) — so a product keeps the whole application range 0x40–0x7F for its own codes. Match them with errs.HasCode. Their Public text is the only part that may reach a caller; none of them is a 4xx, so a caller only ever reads "internal error".

Code 0.4.2.32

const CodeDatabaseOpen errs.Code = 262687

Databases, ADR 0004.

Code 0.4.2.31

const CodeDatabaseUnavailable errs.Code = 262689

The framework's own failures carry SDK error codes in 0.4.2.* — layer 4 is the framework's, PP 2 this package (ADR 0147 §3) — so a product keeps the whole application range 0x40–0x7F for its own codes. Match them with errs.HasCode. Their Public text is the only part that may reach a caller; none of them is a 4xx, so a caller only ever reads "internal error".

Code 0.4.2.33

const CodeDatabaseVersion errs.Code = 262732

The framework's own failures carry SDK error codes in 0.4.2.* — layer 4 is the framework's, PP 2 this package (ADR 0147 §3) — so a product keeps the whole application range 0x40–0x7F for its own codes. Match them with errs.HasCode. Their Public text is the only part that may reach a caller; none of them is a 4xx, so a caller only ever reads "internal error".

Code 0.4.2.76

const CodeHandlerPanic errs.Code = 262666

The framework's own failures carry SDK error codes in 0.4.2.* — layer 4 is the framework's, PP 2 this package (ADR 0147 §3) — so a product keeps the whole application range 0x40–0x7F for its own codes. Match them with errs.HasCode. Their Public text is the only part that may reach a caller; none of them is a 4xx, so a caller only ever reads "internal error".

Code 0.4.2.10

const CodeHistoryLoad errs.Code = 262695

History (ADR 0007).

Code 0.4.2.39

const CodeHistoryMoved errs.Code = 262706

The framework's own failures carry SDK error codes in 0.4.2.* — layer 4 is the framework's, PP 2 this package (ADR 0147 §3) — so a product keeps the whole application range 0x40–0x7F for its own codes. Match them with errs.HasCode. Their Public text is the only part that may reach a caller; none of them is a 4xx, so a caller only ever reads "internal error".

Code 0.4.2.50

const CodeHistoryRead errs.Code = 262697

The framework's own failures carry SDK error codes in 0.4.2.* — layer 4 is the framework's, PP 2 this package (ADR 0147 §3) — so a product keeps the whole application range 0x40–0x7F for its own codes. Match them with errs.HasCode. Their Public text is the only part that may reach a caller; none of them is a 4xx, so a caller only ever reads "internal error".

Code 0.4.2.41

const CodeHistoryWrite errs.Code = 262696

The framework's own failures carry SDK error codes in 0.4.2.* — layer 4 is the framework's, PP 2 this package (ADR 0147 §3) — so a product keeps the whole application range 0x40–0x7F for its own codes. Match them with errs.HasCode. Their Public text is the only part that may reach a caller; none of them is a 4xx, so a caller only ever reads "internal error".

Code 0.4.2.40

const CodeJobOverlapped errs.Code = 262705

The framework's own signals and refusals, typed since the move into the SDK (rule 2: no fmt.Errorf, no errors.New in production code).

Code 0.4.2.49

const CodeKeyRekeyed errs.Code = 262710

The framework's own failures carry SDK error codes in 0.4.2.* — layer 4 is the framework's, PP 2 this package (ADR 0147 §3) — so a product keeps the whole application range 0x40–0x7F for its own codes. Match them with errs.HasCode. Their Public text is the only part that may reach a caller; none of them is a 4xx, so a caller only ever reads "internal error".

Code 0.4.2.54

const CodeLoopNotMounted errs.Code = 262681

The framework's own failures carry SDK error codes in 0.4.2.* — layer 4 is the framework's, PP 2 this package (ADR 0147 §3) — so a product keeps the whole application range 0x40–0x7F for its own codes. Match them with errs.HasCode. Their Public text is the only part that may reach a caller; none of them is a 4xx, so a caller only ever reads "internal error".

Code 0.4.2.25

const CodeLoopPanic errs.Code = 262680

Loops.

Code 0.4.2.24

const CodeLoopStart errs.Code = 262682

The framework's own failures carry SDK error codes in 0.4.2.* — layer 4 is the framework's, PP 2 this package (ADR 0147 §3) — so a product keeps the whole application range 0x40–0x7F for its own codes. Match them with errs.HasCode. Their Public text is the only part that may reach a caller; none of them is a 4xx, so a caller only ever reads "internal error".

Code 0.4.2.26

const CodeMailConfig errs.Code = 262675

Mailers.

Code 0.4.2.19

const CodeMailEncode errs.Code = 262676

The framework's own failures carry SDK error codes in 0.4.2.* — layer 4 is the framework's, PP 2 this package (ADR 0147 §3) — so a product keeps the whole application range 0x40–0x7F for its own codes. Match them with errs.HasCode. Their Public text is the only part that may reach a caller; none of them is a 4xx, so a caller only ever reads "internal error".

Code 0.4.2.20

const CodeMailPanic errs.Code = 262679

The framework's own failures carry SDK error codes in 0.4.2.* — layer 4 is the framework's, PP 2 this package (ADR 0147 §3) — so a product keeps the whole application range 0x40–0x7F for its own codes. Match them with errs.HasCode. Their Public text is the only part that may reach a caller; none of them is a 4xx, so a caller only ever reads "internal error".

Code 0.4.2.23

const CodeMailQueue errs.Code = 262677

The framework's own failures carry SDK error codes in 0.4.2.* — layer 4 is the framework's, PP 2 this package (ADR 0147 §3) — so a product keeps the whole application range 0x40–0x7F for its own codes. Match them with errs.HasCode. Their Public text is the only part that may reach a caller; none of them is a 4xx, so a caller only ever reads "internal error".

Code 0.4.2.21

const CodeMailUndecodable errs.Code = 262678

Deprecated: kit no longer returns it. The outbox is the SDK's mail spool, which dead-letters a record that does not decode itself (MessageUndecodable, in pkg/v1/app/mail/spool).

Code 0.4.2.22

const CodeMigrateRefused errs.Code = 262711

The framework's own failures carry SDK error codes in 0.4.2.* — layer 4 is the framework's, PP 2 this package (ADR 0147 §3) — so a product keeps the whole application range 0x40–0x7F for its own codes. Match them with errs.HasCode. Their Public text is the only part that may reach a caller; none of them is a 4xx, so a caller only ever reads "internal error".

Code 0.4.2.55

const CodeNotMounted errs.Code = 262667

The framework's own failures carry SDK error codes in 0.4.2.* — layer 4 is the framework's, PP 2 this package (ADR 0147 §3) — so a product keeps the whole application range 0x40–0x7F for its own codes. Match them with errs.HasCode. Their Public text is the only part that may reach a caller; none of them is a 4xx, so a caller only ever reads "internal error".

Code 0.4.2.11

const CodeNotSource errs.Code = 262707

The framework's own failures carry SDK error codes in 0.4.2.* — layer 4 is the framework's, PP 2 this package (ADR 0147 §3) — so a product keeps the whole application range 0x40–0x7F for its own codes. Match them with errs.HasCode. Their Public text is the only part that may reach a caller; none of them is a 4xx, so a caller only ever reads "internal error".

Code 0.4.2.51

const CodeNothingToErase errs.Code = 262709

The framework's own failures carry SDK error codes in 0.4.2.* — layer 4 is the framework's, PP 2 this package (ADR 0147 §3) — so a product keeps the whole application range 0x40–0x7F for its own codes. Match them with errs.HasCode. Their Public text is the only part that may reach a caller; none of them is a 4xx, so a caller only ever reads "internal error".

Code 0.4.2.53

const CodePasswordHash errs.Code = 262698

The framework's own failures carry SDK error codes in 0.4.2.* — layer 4 is the framework's, PP 2 this package (ADR 0147 §3) — so a product keeps the whole application range 0x40–0x7F for its own codes. Match them with errs.HasCode. Their Public text is the only part that may reach a caller; none of them is a 4xx, so a caller only ever reads "internal error".

Code 0.4.2.42

const CodePasswordMoved errs.Code = 262708

The framework's own failures carry SDK error codes in 0.4.2.* — layer 4 is the framework's, PP 2 this package (ADR 0147 §3) — so a product keeps the whole application range 0x40–0x7F for its own codes. Match them with errs.HasCode. Their Public text is the only part that may reach a caller; none of them is a 4xx, so a caller only ever reads "internal error".

Code 0.4.2.52

const CodePrivacyData errs.Code = 262694

The framework's own failures carry SDK error codes in 0.4.2.* — layer 4 is the framework's, PP 2 this package (ADR 0147 §3) — so a product keeps the whole application range 0x40–0x7F for its own codes. Match them with errs.HasCode. Their Public text is the only part that may reach a caller; none of them is a 4xx, so a caller only ever reads "internal error".

Code 0.4.2.38

const CodePrivacyErase errs.Code = 262692

The framework's own failures carry SDK error codes in 0.4.2.* — layer 4 is the framework's, PP 2 this package (ADR 0147 §3) — so a product keeps the whole application range 0x40–0x7F for its own codes. Match them with errs.HasCode. Their Public text is the only part that may reach a caller; none of them is a 4xx, so a caller only ever reads "internal error".

Code 0.4.2.36

const CodePrivacyJournal errs.Code = 262693

The framework's own failures carry SDK error codes in 0.4.2.* — layer 4 is the framework's, PP 2 this package (ADR 0147 §3) — so a product keeps the whole application range 0x40–0x7F for its own codes. Match them with errs.HasCode. Their Public text is the only part that may reach a caller; none of them is a 4xx, so a caller only ever reads "internal error".

Code 0.4.2.37

const CodePrivacyKey errs.Code = 262691

Privacy (ADR 0006).

Code 0.4.2.35

const CodeProfileRead errs.Code = 262704

CodeProfileRead reports a profile of the process that could not be written or read back. It is in the framework's 0.4.2.* range.

Code 0.4.2.48

const CodeQueueOpen errs.Code = 262664

The framework's own failures carry SDK error codes in 0.4.2.* — layer 4 is the framework's, PP 2 this package (ADR 0147 §3) — so a product keeps the whole application range 0x40–0x7F for its own codes. Match them with errs.HasCode. Their Public text is the only part that may reach a caller; none of them is a 4xx, so a caller only ever reads "internal error".

Code 0.4.2.8

const CodeRecordsKeys errs.Code = 262733

The framework's own failures carry SDK error codes in 0.4.2.* — layer 4 is the framework's, PP 2 this package (ADR 0147 §3) — so a product keeps the whole application range 0x40–0x7F for its own codes. Match them with errs.HasCode. Their Public text is the only part that may reach a caller; none of them is a 4xx, so a caller only ever reads "internal error".

Code 0.4.2.77

const CodeResealInPlace errs.Code = 262728

The framework's own failures carry SDK error codes in 0.4.2.* — layer 4 is the framework's, PP 2 this package (ADR 0147 §3) — so a product keeps the whole application range 0x40–0x7F for its own codes. Match them with errs.HasCode. Their Public text is the only part that may reach a caller; none of them is a 4xx, so a caller only ever reads "internal error".

Code 0.4.2.72

const CodeResealMoved errs.Code = 262729

The framework's own failures carry SDK error codes in 0.4.2.* — layer 4 is the framework's, PP 2 this package (ADR 0147 §3) — so a product keeps the whole application range 0x40–0x7F for its own codes. Match them with errs.HasCode. Their Public text is the only part that may reach a caller; none of them is a 4xx, so a caller only ever reads "internal error".

Code 0.4.2.73

const CodeRetentionPanic errs.Code = 262713

The framework's own failures carry SDK error codes in 0.4.2.* — layer 4 is the framework's, PP 2 this package (ADR 0147 §3) — so a product keeps the whole application range 0x40–0x7F for its own codes. Match them with errs.HasCode. Their Public text is the only part that may reach a caller; none of them is a 4xx, so a caller only ever reads "internal error".

Code 0.4.2.57

const CodeRevisionDecode errs.Code = 262725

The framework's own failures carry SDK error codes in 0.4.2.* — layer 4 is the framework's, PP 2 this package (ADR 0147 §3) — so a product keeps the whole application range 0x40–0x7F for its own codes. Match them with errs.HasCode. Their Public text is the only part that may reach a caller; none of them is a 4xx, so a caller only ever reads "internal error".

Code 0.4.2.69

const CodeRevisionRead errs.Code = 262723

Revisions (ADR 0007 §3).

Code 0.4.2.67

const CodeRevisionWrite errs.Code = 262724

The framework's own failures carry SDK error codes in 0.4.2.* — layer 4 is the framework's, PP 2 this package (ADR 0147 §3) — so a product keeps the whole application range 0x40–0x7F for its own codes. Match them with errs.HasCode. Their Public text is the only part that may reach a caller; none of them is a 4xx, so a caller only ever reads "internal error".

Code 0.4.2.68

const CodeScopeUnknown errs.Code = 262716

CodeScopeUnknown reports a scope whose value could not be read at the start: no current user, no executable path, no configuration directory.

Code 0.4.2.60

const CodeSealErased errs.Code = 262726

The signals kit ends one of its own steps with and catches itself — a caller never receives one —, typed when the SDK made rule 2 a gate (make guard), where they had been stdlib errors.

Code 0.4.2.70

const CodeSealKey errs.Code = 262717

Sealing at rest (ADR 0006, step 3).

Code 0.4.2.61

const CodeSealKeyMoved errs.Code = 262727

The framework's own failures carry SDK error codes in 0.4.2.* — layer 4 is the framework's, PP 2 this package (ADR 0147 §3) — so a product keeps the whole application range 0x40–0x7F for its own codes. Match them with errs.HasCode. Their Public text is the only part that may reach a caller; none of them is a 4xx, so a caller only ever reads "internal error".

Code 0.4.2.71

const CodeSealOpen errs.Code = 262719

The framework's own failures carry SDK error codes in 0.4.2.* — layer 4 is the framework's, PP 2 this package (ADR 0147 §3) — so a product keeps the whole application range 0x40–0x7F for its own codes. Match them with errs.HasCode. Their Public text is the only part that may reach a caller; none of them is a 4xx, so a caller only ever reads "internal error".

Code 0.4.2.63

const CodeSealRewrap errs.Code = 262720

The framework's own failures carry SDK error codes in 0.4.2.* — layer 4 is the framework's, PP 2 this package (ADR 0147 §3) — so a product keeps the whole application range 0x40–0x7F for its own codes. Match them with errs.HasCode. Their Public text is the only part that may reach a caller; none of them is a 4xx, so a caller only ever reads "internal error".

Code 0.4.2.64

const CodeSealShred errs.Code = 262721

The framework's own failures carry SDK error codes in 0.4.2.* — layer 4 is the framework's, PP 2 this package (ADR 0147 §3) — so a product keeps the whole application range 0x40–0x7F for its own codes. Match them with errs.HasCode. Their Public text is the only part that may reach a caller; none of them is a 4xx, so a caller only ever reads "internal error".

Code 0.4.2.65

const CodeSealWrite errs.Code = 262718

The framework's own failures carry SDK error codes in 0.4.2.* — layer 4 is the framework's, PP 2 this package (ADR 0147 §3) — so a product keeps the whole application range 0x40–0x7F for its own codes. Match them with errs.HasCode. Their Public text is the only part that may reach a caller; none of them is a 4xx, so a caller only ever reads "internal error".

Code 0.4.2.62

const CodeSecretMissing errs.Code = 262684

The framework's own failures carry SDK error codes in 0.4.2.* — layer 4 is the framework's, PP 2 this package (ADR 0147 §3) — so a product keeps the whole application range 0x40–0x7F for its own codes. Match them with errs.HasCode. Their Public text is the only part that may reach a caller; none of them is a 4xx, so a caller only ever reads "internal error".

Code 0.4.2.28

const CodeSecretRead errs.Code = 262685

The framework's own failures carry SDK error codes in 0.4.2.* — layer 4 is the framework's, PP 2 this package (ADR 0147 §3) — so a product keeps the whole application range 0x40–0x7F for its own codes. Match them with errs.HasCode. Their Public text is the only part that may reach a caller; none of them is a 4xx, so a caller only ever reads "internal error".

Code 0.4.2.29

const CodeSecretRotate errs.Code = 262686

The framework's own failures carry SDK error codes in 0.4.2.* — layer 4 is the framework's, PP 2 this package (ADR 0147 §3) — so a product keeps the whole application range 0x40–0x7F for its own codes. Match them with errs.HasCode. Their Public text is the only part that may reach a caller; none of them is a 4xx, so a caller only ever reads "internal error".

Code 0.4.2.30

const CodeSecretStore errs.Code = 262683

Secrets.

Code 0.4.2.27

const CodeSingletonHeld errs.Code = 262714

CodeSingletonHeld reports a start refused because another process of the app holds its singleton lock.

Code 0.4.2.58

const CodeStoreDecode errs.Code = 262657

The framework's own failures carry SDK error codes in 0.4.2.* — layer 4 is the framework's, PP 2 this package (ADR 0147 §3) — so a product keeps the whole application range 0x40–0x7F for its own codes. Match them with errs.HasCode. Their Public text is the only part that may reach a caller; none of them is a 4xx, so a caller only ever reads "internal error".

Code 0.4.2.1

const CodeStoreEncode errs.Code = 262658

The framework's own failures carry SDK error codes in 0.4.2.* — layer 4 is the framework's, PP 2 this package (ADR 0147 §3) — so a product keeps the whole application range 0x40–0x7F for its own codes. Match them with errs.HasCode. Their Public text is the only part that may reach a caller; none of them is a 4xx, so a caller only ever reads "internal error".

Code 0.4.2.2

const CodeStoreIndex errs.Code = 262661

The framework's own failures carry SDK error codes in 0.4.2.* — layer 4 is the framework's, PP 2 this package (ADR 0147 §3) — so a product keeps the whole application range 0x40–0x7F for its own codes. Match them with errs.HasCode. Their Public text is the only part that may reach a caller; none of them is a 4xx, so a caller only ever reads "internal error".

Code 0.4.2.5

const CodeStoreLoad errs.Code = 262660

The framework's own failures carry SDK error codes in 0.4.2.* — layer 4 is the framework's, PP 2 this package (ADR 0147 §3) — so a product keeps the whole application range 0x40–0x7F for its own codes. Match them with errs.HasCode. Their Public text is the only part that may reach a caller; none of them is a 4xx, so a caller only ever reads "internal error".

Code 0.4.2.4

const CodeStorePersist errs.Code = 262659

The framework's own failures carry SDK error codes in 0.4.2.* — layer 4 is the framework's, PP 2 this package (ADR 0147 §3) — so a product keeps the whole application range 0x40–0x7F for its own codes. Match them with errs.HasCode. Their Public text is the only part that may reach a caller; none of them is a 4xx, so a caller only ever reads "internal error".

Code 0.4.2.3

const CodeTopicEncode errs.Code = 262662

The framework's own failures carry SDK error codes in 0.4.2.* — layer 4 is the framework's, PP 2 this package (ADR 0147 §3) — so a product keeps the whole application range 0x40–0x7F for its own codes. Match them with errs.HasCode. Their Public text is the only part that may reach a caller; none of them is a 4xx, so a caller only ever reads "internal error".

Code 0.4.2.6

const CodeTopicPublish errs.Code = 262663

The framework's own failures carry SDK error codes in 0.4.2.* — layer 4 is the framework's, PP 2 this package (ADR 0147 §3) — so a product keeps the whole application range 0x40–0x7F for its own codes. Match them with errs.HasCode. Their Public text is the only part that may reach a caller; none of them is a 4xx, so a caller only ever reads "internal error".

Code 0.4.2.7

const CodeTransactionPanic errs.Code = 262731

The framework's own failures carry SDK error codes in 0.4.2.* — layer 4 is the framework's, PP 2 this package (ADR 0147 §3) — so a product keeps the whole application range 0x40–0x7F for its own codes. Match them with errs.HasCode. Their Public text is the only part that may reach a caller; none of them is a 4xx, so a caller only ever reads "internal error".

Code 0.4.2.75

const CodeTransactionSpan errs.Code = 262722

A transaction wrote a store another database keeps than the one it belongs to — the data directory counting as one: refused, Invalid.

Code 0.4.2.66

const CodeUndecodable errs.Code = 262665

The framework's own failures carry SDK error codes in 0.4.2.* — layer 4 is the framework's, PP 2 this package (ADR 0147 §3) — so a product keeps the whole application range 0x40–0x7F for its own codes. Match them with errs.HasCode. Their Public text is the only part that may reach a caller; none of them is a 4xx, so a caller only ever reads "internal error".

Code 0.4.2.9

const CodeWatchQueue errs.Code = 262703

Watches (ADR 0008).

Code 0.4.2.47

const CodeWorkflowHookChange errs.Code = 262670

An OnEnter hook changed the state its entity was entering, or the entity's key: the transition is refused.

Code 0.4.2.14

const CodeWorkflowHookPanic errs.Code = 262669

A workflow hook panicked: an OnEnter hook fails its transition with it, an OnTransition hook is reported and the transition stands.

Code 0.4.2.13

const CodeWorkflowLoad errs.Code = 262668

The framework's own failures carry SDK error codes in 0.4.2.* — layer 4 is the framework's, PP 2 this package (ADR 0147 §3) — so a product keeps the whole application range 0x40–0x7F for its own codes. Match them with errs.HasCode. Their Public text is the only part that may reach a caller; none of them is a 4xx, so a caller only ever reads "internal error".

Code 0.4.2.12

const CodeWorkflowNotInPlace errs.Code = 262730

The framework's own failures carry SDK error codes in 0.4.2.* — layer 4 is the framework's, PP 2 this package (ADR 0147 §3) — so a product keeps the whole application range 0x40–0x7F for its own codes. Match them with errs.HasCode. Their Public text is the only part that may reach a caller; none of them is a 4xx, so a caller only ever reads "internal error".

Code 0.4.2.74

const CodeWorkflowReentrant errs.Code = 262671

An OnEnter hook fired its own workflow: refused, where it would wait for itself.

Code 0.4.2.15

const DefaultMaxBody int64 = 1048576

DefaultMaxBody is the largest request body an endpoint reads, unless the endpoint says otherwise with MaxBody.

const EnvDev = "dev"

EnvDev serves the Studio, analyzes the source and binds loopback. Only `kit dev` or an explicit KIT_ENV=dev turns it on.

const EnvProduction = "production"

EnvProduction is the default: no Studio, no source, no analysis.

const Moderated Mark = "moderated"

Moderated marks content others see and a moderator may act on.

const Personal Mark = "personal"

Personal marks a field that holds data about a person: personal, special, or a record's subject.

const Special Mark = "special"

Special marks a field of GDPR art. 9(1) or art. 10.

const WireCanceled = "canceled"

The wire codes a caller branches on: an Error's Code, snake_case, kept byte-for-byte from the platform's kit (ADR 0147 §6). They are named Wire*, not Code*, because Code* names a dotted-quad errs.Code in the SDK and the registry audit holds every Code* constant to that.

const WireConflict = "conflict"

The wire codes a caller branches on: an Error's Code, snake_case, kept byte-for-byte from the platform's kit (ADR 0147 §6). They are named Wire*, not Code*, because Code* names a dotted-quad errs.Code in the SDK and the registry audit holds every Code* constant to that.

const WireForbidden = "permission_denied"

The wire codes a caller branches on: an Error's Code, snake_case, kept byte-for-byte from the platform's kit (ADR 0147 §6). They are named Wire*, not Code*, because Code* names a dotted-quad errs.Code in the SDK and the registry audit holds every Code* constant to that.

const WireInternal = "internal"

The wire codes a caller branches on: an Error's Code, snake_case, kept byte-for-byte from the platform's kit (ADR 0147 §6). They are named Wire*, not Code*, because Code* names a dotted-quad errs.Code in the SDK and the registry audit holds every Code* constant to that.

const WireInvalid = "invalid_argument"

The wire codes a caller branches on: an Error's Code, snake_case, kept byte-for-byte from the platform's kit (ADR 0147 §6). They are named Wire*, not Code*, because Code* names a dotted-quad errs.Code in the SDK and the registry audit holds every Code* constant to that.

const WireNotFound = "not_found"

The wire codes a caller branches on: an Error's Code, snake_case, kept byte-for-byte from the platform's kit (ADR 0147 §6). They are named Wire*, not Code*, because Code* names a dotted-quad errs.Code in the SDK and the registry audit holds every Code* constant to that.

const WireRateLimited = "rate_limited"

The wire codes a caller branches on: an Error's Code, snake_case, kept byte-for-byte from the platform's kit (ADR 0147 §6). They are named Wire*, not Code*, because Code* names a dotted-quad errs.Code in the SDK and the registry audit holds every Code* constant to that.

const WireTimeout = "deadline_exceeded"

The wire codes a caller branches on: an Error's Code, snake_case, kept byte-for-byte from the platform's kit (ADR 0147 §6). They are named Wire*, not Code*, because Code* names a dotted-quad errs.Code in the SDK and the registry audit holds every Code* constant to that.

const WireTooLarge = "too_large"

The wire codes a caller branches on: an Error's Code, snake_case, kept byte-for-byte from the platform's kit (ADR 0147 §6). They are named Wire*, not Code*, because Code* names a dotted-quad errs.Code in the SDK and the registry audit holds every Code* constant to that.

const WireUnauth = "unauthenticated"

The wire codes a caller branches on: an Error's Code, snake_case, kept byte-for-byte from the platform's kit (ADR 0147 §6). They are named Wire*, not Code*, because Code* names a dotted-quad errs.Code in the SDK and the registry audit holds every Code* constant to that.

const WireUnavailable = "unavailable"

The wire codes a caller branches on: an Error's Code, snake_case, kept byte-for-byte from the platform's kit (ADR 0147 §6). They are named Wire*, not Code*, because Code* names a dotted-quad errs.Code in the SDK and the registry audit holds every Code* constant to that.

const WireUnsupported = "unsupported_media_type"

The wire codes a caller branches on: an Error's Code, snake_case, kept byte-for-byte from the platform's kit (ADR 0147 §6). They are named Wire*, not Code*, because Code* names a dotted-quad errs.Code in the SDK and the registry audit holds every Code* constant to that.

Variables

var PerConfigDir ScopeValue

PerConfigDir is the user's configuration directory (os.UserConfigDir): one process per configuration home.

var PerExecutable ScopeValue

PerExecutable is the running executable's path, links resolved: one process per installed copy of the binary.

var PerUID ScopeValue

PerUID is the current user: one process per user of the machine (its UID on Unix, its SID on Windows).

var Privacy *Service

Privacy is kit's own service: the data keys, the legal holds and the privacy journal of an app that keeps personal data or seals what it keeps. kit mounts a copy of it — named kit.privacy, a name no service of a product can take — in every app whose stores keep personal data or declare a retention, or that keeps sealed values at rest, before the product's services. Its stores stay in the data directory unless the product places them (ADR 0004): kit.Keeps(kit.Privacy). On a SQLite database its data keys stay in the data directory all the same — a key is written apart from every transaction, and the file's one writer may be held by the transaction of the write that needs it —; its holds and its journal go there. A product never mounts it itself.

func After

func After(ctx context.Context, d time.Duration) <-chan time.Time

After is time.After on the app's clock.

func AllowPeers

func AllowPeers(uids []int, gids []int) ListenerConfigurer

AllowPeers admits accounts besides the product's own: an on-call group declared at deployment. The kernel checks them where it names the peer; the socket's directory must still let them through, which is the deployment's to arrange.

IFACE-OPAQUE: ListenerOption is sealed — its one method is unexported — so only this package makes one, and a caller only passes it to Listen.

func Analyze

func Analyze(on bool) AppConfigurer

Analyze switches the in-process static analysis on or off in dev.

func Analyzer

func Analyzer(fn AnalyzeFunc) AppConfigurer

Analyzer runs fn in the background once the product serves, in dev and when KIT_ANALYZE allows it. Without one, the graph is the runtime's alone.

func Anonymise

func Anonymise[T any](fn func(*T)) StoreConfigurer

Anonymise says what an erased record keeps: fn runs first, and generalises into unclassified fields — a birth date to its year, an address to its region; then kit clears the rest. kit cannot prove that what remains identifies no one: by declaring the function, the product asserts it.

func AnyUser

func AnyUser() ExposeConfigurer

AnyUser says that an exposure is open to any signed-in user, on purpose: its operation asks for a user (Auth) and declares no permission and no rule — its handler reads UserID and keeps to what that user owns.

var MyOrders = Service.Query("my-orders", myOrders, kit.Auth()).Expose("GET /orders", kit.AnyUser())

It adds no authentication of its own: an exposure authenticates as its operation asks, so the operation declares Auth.

func Anyone

func Anyone() ExposeConfigurer

Anyone says that an exposure is open to everyone, on purpose: its operation declares no permission and no rule, and whoever reaches the route may run it — a public form, say. It says so on the exposure's node, where the diagram and the API page read it. An exposure whose operation declares no rule refuses the start unless it says this, or AnyUser.

var Report = Service.Command("report", file).Expose("POST /reports", kit.Anyone())

It adds no authentication: an operation that asks for a user (Auth) takes AnyUser instead, and one with AuthOptional still knows the caller who signed in.

func Auth

func Auth() OperationOption

Auth makes an endpoint require an authenticated caller: the app's auth handler runs first, and a request without valid credentials is answered 401 before the handler runs. A command or a query that asks for one is refused 401 when its caller carries no user: an in-process dispatch carries its caller's, and is not authenticated again.

IFACE-OPAQUE: the option is sealed — its method is unexported — so a caller only hands it to the declaration it configures.

func AuthData

func AuthData[D any](ctx context.Context) (D, bool)

AuthData returns what the auth handler said about the caller, and whether there is a caller whose data has type D.

func AuthOptional

func AuthOptional() OperationOption

AuthOptional runs the app's auth handler when the request carries credentials, and serves anonymous callers too: UserID tells which.

IFACE-OPAQUE: the option is sealed — its method is unexported — so a caller only hands it to the declaration it configures.

func Bind

func Bind[Req, Resp any](port *PortService[Req, Resp], op Operation[Req, Resp]) interface{AppConfigurer; MountConfigurer}

Bind makes the app's port call op, whatever implements the port and whatever its fallback: an endpoint — or, with ADR 0005, a command or a query — of the port's types. A binding is code, the same in every environment; a binding to a port, or to a service the app does not mount, is refused when the app starts. Given twice for one port, the last wins.

app := kit.NewApp("vigie", desk.Service, posts.Service).With(kit.Bind(desk.Enforcer, posts.EnforceAPI))

It is an option of Mount too, under the same name: there it binds a port of the module mounted, and another is refused.

app := kit.NewApp("shop", posts.Service).With(kit.Mount(moderation.Module, kit.Bind(moderation.Enforcer, posts.EnforceAPI)))

func Bulkhead

func Bulkhead(maxConcurrent int) OperationOption

Bulkhead caps how many requests the handler serves at once; the overflow answers 503. It is the SDK's resilience bulkhead.

IFACE-OPAQUE: the option is sealed — its method is unexported — so a caller only hands it to the declaration it configures.

func Catalog

func Catalog() []model.Mechanic

Catalog lists the generic mechanics kit offers: the building blocks a node composes rather than implements, each one backed by an SDK package. It is part of every graph, so the Studio — and an AI agent reading the graph — knows what can be added to a product and the exact code that adds it.

func ClearCookie

func ClearCookie(ctx context.Context, name string)

ClearCookie tells the browser to forget the cookie called name.

func ClientIP

func ClientIP(ctx context.Context) string

ClientIP returns the address of the client of the request ctx serves: the connection's peer, or — only when KIT_TRUST_PROXY=on — the last address of X-Forwarded-For, the one the trusted proxy appended. It is "" outside an HTTP request.

func Clock

func Clock(c clock.Timed) AppConfigurer

Clock makes the app read and wait on c instead of the system clock: a test drives timer transitions and jobs with a clock.ManualClock.

func ConfigFiles

func ConfigFiles(fsys fs.FS) AppConfigurer

ConfigFiles gives kit the product's configuration files: config/config.<ext>, which every environment reads, and config/<env>.<ext>, the environment's own — <env> being KIT_ENV as written, dev when kit dev runs the product — in JSON, YAML or TOML (json, yaml or yml, toml). A file maps the names of the settings to their values; it never holds a secret, and a key no service declares stops the start. The files belong in the binary:

//go:embed config
var configFiles embed.FS

app := kit.NewApp("todo", ...).With(kit.ConfigFiles(configFiles))

func Conflict

func Conflict(message string) *Error

Conflict reports a request the resource's current state refuses (409).

func DataDir

func DataDir(dir string) AppConfigurer

DataDir sets where stores and queues persist, instead of KIT_DATA_DIR. Given to an app after InMemory, it wins: the last of the two says where the data is — so a test helper that runs the product in memory runs it on disk with the one option its test gives (kittest.NewDisk).

func Database

func Database(name string, engine Engine, opts ...DatabaseConfigurer) AppConfigurer

Database declares a database the product keeps its stores in, named name, on engine — an engine module's, which the product's main imports:

import (
	"github.com/kitsunium/sdk/framework/connectors/postgres"
	"github.com/kitsunium/sdk/framework/connectors/sqlite"
)

var App = kit.NewApp("vigie", intake.Service, desk.Service, audit.Service).With(
	// Keeps every store no other database keeps.
	kit.Database("database", postgres.Engine()),
	// The audit trail apart.
	kit.Database("archive", sqlite.Engine(), kit.Keeps(audit.Service)),
)

name is 1 to 49 lower-case letters, digits and dashes, not starting with "kit-", unique among the app's databases. It names the database's URL, the secret <name>-url — the variable <APP>_<NAME>_URL, or <APP>_<NAME>_URL_FILE naming a file that holds it, then the environment's secret store —, and its settings: <name>-max-open (10), <name>-max-idle (2), <name>-max-lifetime (30m), <name>-max-idle-time (0: none), <name>-timeout (5s), <name>-check-timeout (5s) and <name>-migrate (start, or manual). Outside dev the URL is required and writes its TLS mode; in dev a database without one leaves its stores in the data directory, and a SQLite database without one is the file <data>/<name>.sqlite. InMemory on the app opens none.

func DefaultCommand

func DefaultCommand() CommandLineConfigurer

DefaultCommand makes the command Main's default: it runs with every argument when the first names no other command — neither one of the product's nor one of Main's (serve, help…) —, and with none when there is none. Main then never answers a usage error. One command of an app may be its default.

IFACE-OPAQUE: CLIOption is sealed — its one method is unexported — so only this package makes one, and a caller only passes it to CLI.

func DeleteAfter

func DeleteAfter[T any, D Delay](delay D, since func(T) (time.Time, bool)) StoreConfigurer

DeleteAfter deletes a record delay after the instant since returns.

func DeleteAt

func DeleteAt[T any](at func(T) (time.Time, bool)) StoreConfigurer

DeleteAt deletes a record at the instant at returns.

func DeleteOnErasure

func DeleteOnErasure() StoreConfigurer

DeleteOnErasure makes a person's erasure (kit.Erase) delete the store's records instead of clearing them, as sessions and accounts want.

func DesignDigest

func DesignDigest(digest string) AppConfigurer

DesignDigest records the digest of the design the product's code was generated from — what the generated wiring passes —, so the telemetry handshake can say it and a tool attached to the product can tell a process built from another design.

func EnableServer

func EnableServer()

EnableServer makes an app in the server profile serve HTTP. framework/kit/server calls it as it is imported; a product never does.

func EnableStudio

func EnableStudio()

EnableStudio makes a serving app in dev mount the Studio's API. framework/kit/studio calls it as it is imported; a product never does.

func Env

func Env(env string) AppConfigurer

Env selects the environment, instead of KIT_ENV.

func Erase

func Erase(ctx context.Context, reason string, ids ...string) (Erasure, error)

Erase erases every record whose subject is one of ids, in every store of the app, as its retention would — or deletes it where the store says kit.DeleteOnErasure — and folds the stores it wrote, so that what it overwrote leaves their files. A held record is left in place, and the result says so: it lists, per store, what was erased, deleted and held. Telling the recipients (GDPR art. 19) is the product's job; the register lists them. reason is journaled.

What kit seals at rest, it erases cryptographically too (ADR 0006 §4): a held record is moved under a data key of its own, then the data key of each identity, and every data key the erased records were sealed under, is destroyed — every copy of what they sealed stops opening: a store's former values, a dead letter, a backup. An erasure that failed in a store destroys nothing: its retry does.

func EraseAfter

func EraseAfter[T any, D Delay](delay D, since func(T) (time.Time, bool)) StoreConfigurer

EraseAfter erases a record's personal data delay after the instant since returns — its closing, say; false means "not yet": an open record is never due. delay is a duration, or a duration setting.

func EraseAt

func EraseAt[T any](at func(T) (time.Time, bool)) StoreConfigurer

EraseAt erases a record's personal data at the instant at returns: one the product computed and stored on the record — a retention in calendar months, one that depends on a tenant.

func Export

func Export(ctx context.Context, ids ...string) (PersonalData, error)

Export returns every record whose subject is one of ids, in every store of the app: each without its secret members, with the former values its fields keep (ADR 0007) — never a secret field's — and the versions its store keeps of it, without their secret members, and per store what GDPR art. 15(1) asks beside the data — the purpose, the retention and the recipients inside the product. A held record is exported like any other. The result is JSON, structured and machine-readable (art. 20); keeping the month of art. 12(3) is the product's job, and so is deciding who may call it.

A person known under several identities — a user's ID in one store, an e-mail address in another — is found by giving all of them. ctx must run inside the app: an endpoint's, a job's, a loop's.

func FailSafe

func FailSafe() CommandLineConfigurer

FailSafe makes the command's status always 0: a status line, a prompt hook, anything a shell runs on every keystroke must never fail the shell. A non-zero status, a start that fails and a panic are logged instead.

IFACE-OPAQUE: CLIOption is sealed — its one method is unexported — so only this package makes one, and a caller only passes it to CLI.

func Fallback

func Fallback[Req, Resp any](op Operation[Req, Resp]) PortConfigurer[Req, Resp]

Fallback gives a port an implementation from its own side, which it calls when the app binds nothing else: an endpoint — or, with ADR 0005, a command or a query — of the port's types. A port given here is refused when the app starts.

var Enforcer = Service.Port[Measure, Applied]("enforcer", kit.Fallback(QueueAPI))

IFACE-OPAQUE: the option is sealed — its method is unexported — so a caller only hands it to the declaration it configures.

func Forbidden

func Forbidden(message string) *Error

Forbidden reports a caller who may not do this (403).

func From

func From(name string, addr string) MailerConfigurer

From sets the sender of every message that names none.

IFACE-OPAQUE: the option is sealed — its method is unexported — so a caller only hands it to the declaration it configures.

func Generated

func Generated(bytes int) SecretConfigurer

Generated makes the secret kit's to make: versions of bytes random bytes — 32 for a key — the first made on the first start, a new one every 30 days, the last 3 kept, unless RotateEvery and KeepVersions say otherwise.

IFACE-OPAQUE: the option is sealed — its method is unexported — so a caller only hands it to the declaration it configures.

func HeldUntil

func HeldUntil[T any](until func(T) (time.Time, bool), reason string) StoreConfigurer

HeldUntil holds each record until the instant until returns: the law's own retention, such as an invoice kept ten years (GDPR art. 17(3)(b)). reason is the legal ground, for the register. A held record is exported and updated like any other, and neither erased nor deleted.

func HoldSubject

func HoldSubject(ctx context.Context, reason string, ids ...string) error

HoldSubject places a legal hold on every record whose subject is one of ids, in every store of the app: an authority's request about a person. It holds the records they have now; a record written later is not held. reason is kept as Store.Hold keeps it.

func IdleStop

func IdleStop(d time.Duration) AppConfigurer

IdleStop makes a daemon stop itself once, for d, no connection was open on any of its listeners and no activity of its services (Service.Activity) said it was busy: a daemon launched on demand by its clients ends when they stop coming. It is refused outside the daemon profile.

func InMemory

func InMemory() interface{StoreConfigurer; AppConfigurer}

InMemory keeps data in memory. On an app, it overrides the data directory for every store and queue — KIT_DATA_DIR, and a DataDir given before it: what a test wants. On a store, it keeps that store in memory even when the app has a data directory.

func Index

func Index[T any](name string, keys func(T) []string) StoreConfigurer

Index declares an index where an entity may have several keys and a key several entities — the users a task is shared with. StoreService.Find reads it. Empty keys are not indexed.

func Invalid

func Invalid(message string) *Error

Invalid reports a request the caller must change before retrying (400).

func KeepVersions

func KeepVersions(n int) SecretConfigurer

KeepVersions is how many versions of a generated secret a rotation leaves, the new one included: at least 2, so that what the version it replaces sealed or signed still opens and verifies. Cover the longest-lived box or signature in flight: its lifetime divided by the interval, plus one.

IFACE-OPAQUE: the option is sealed — its method is unexported — so a caller only hands it to the declaration it configures.

func Keeps

func Keeps(things ...Keeper) DatabaseConfigurer

Keeps says what the database keeps: a service's stores, a store, a module's stores. The most precise wins: a store kept by name, then its service, then its module, then the default database — the one declared without Keeps —, then the data directory, then memory. InMemory wins over all of them, on the app as on a store. kit's data keys never live on SQLite: Keeps(kit.Privacy) there keeps its holds and its journal (Privacy).

func Listen

func Listen(addr string) AppConfigurer

Listen sets the listening address, instead of KIT_ADDR or PORT. ":0" picks a free port; App.URL tells which.

func Log

func Log(ctx context.Context) logger.Logger

Log returns the app's logger, for the node ctx runs inside. In dev, every record it writes inside a span is also kept beside that span, so the Studio shows a request's logs with its trace.

func Logs

func Logs(w io.Writer) AppConfigurer

Logs sends the app's logs to w instead of standard error.

func MailAttempts

func MailAttempts(n int) MailerConfigurer

MailAttempts is how many deliveries a message gets before it is dead-lettered. The default is 6, backing off from one second.

IFACE-OPAQUE: the option is sealed — its method is unexported — so a caller only hands it to the declaration it configures.

func MaxBody

func MaxBody(bytes int64) EndpointConfigurer

MaxBody bounds the request body the endpoint reads. The default is DefaultMaxBody.

func MaxDeliveries

func MaxDeliveries(n int) DeliveryOption

MaxDeliveries is how many attempts a message gets before it is dead-lettered — a subscription's, or a queued command's. The default is 5.

IFACE-OPAQUE: the option is sealed — its method is unexported — so a caller only hands it to the declaration it configures.

func Migrations

func Migrations(m ...sql.Migration) interface{DatabaseConfigurer; ModuleConfigurer}

Migrations are migrations, values of the SDK's sql.Migration, run when the database starts (<name>-migrate: start) or by `<product> migrate up`, kit's own first, each set under its own version table — and so its own lock. On MySQL a DDL statement commits by itself: write one per migration.

Given to Database, they are the product's, under schema_migrations. Given to NewModule, they are the module's (ADR 0008), for the data it keeps outside kit's stores: run on the database that keeps the module, under <module>_migrations.

func MinLength

func MinLength(n int) PasswordConfigurer

MinLength refuses a password shorter than n characters, counted as NIST counts them: one per Unicode code point. The default is 15, NIST's figure for a password used alone; 8 is the floor NIST allows with a second factor, and a smaller n is refused. There is no composition rule, ever: NIST says SHALL NOT.

IFACE-OPAQUE: the option is sealed — its method is unexported — so a caller only hands it to the declaration it configures.

func Mount

func Mount(m *Module, opts ...MountConfigurer) AppConfigurer

Mount mounts module m with options: Prefix serves its routes elsewhere than "/<module>/", Bind chooses what one of its ports calls.

app := kit.NewApp("vigie", identity.Service).
	With(kit.Mount(moderation.Module, kit.Prefix("/"), kit.Bind(moderation.Enforcer, posts.EnforceAPI)))

A module is mounted once per app: mounted again, its prefix is the last one given, and its bindings join the others, the last of a port winning.

func Name

func Name(name string) EndpointConfigurer

Name overrides the endpoint's name, which otherwise is its handler's function name, or its route when the handler is a function literal.

func NewApp

func NewApp(name string, services ...*Service) *App

NewApp declares the product named name, made of services. A module's services come with the module: App.With mounts it.

func NewBinary

func NewBinary(name string, doc string) *Binary

NewBinary declares the binary named name.

func NewCommand

func NewCommand[C, R any]() *Command[C, R]

NewCommand is a command no service declares yet: Service.Command makes one and declares it, which is how a product gets one.

func NewEndpointService

func NewEndpointService[Req, Resp any]() *EndpointService[Req, Resp]

NewEndpointService is an endpoint no service declares yet: Service.Endpoint makes one and declares it, which is how a product gets one.

func NewError

func NewError(status int, code string, message string) *Error

NewError is an error answered with the HTTP status, carrying the wire code and the message a caller reads.

func NewID

func NewID(prefix string) string

NewID returns a new identifier with the given prefix: a TypeID, time ordered, like "todo_01k5zq7m3xe8tvbfg0s7zr4w6c". The prefix must be one to sixty-three lower-case letters, with '_' only between two letters; any other prefix is a programming error and panics.

func NewListener

func NewListener(contract string, handler ListenHandler) *Listener

NewListener is a listener no service declares yet, speaking contract and served by handler: Service.Listen makes one and declares it, which is how a product gets one.

func NewLoop

func NewLoop(run func(context.Context, WakeEvent) error) *Loop

NewLoop is a loop no service declares yet, whose runs are run: Service.Loop makes one and declares it, which is how a product gets one.

func NewMailer

func NewMailer() *Mailer

NewMailer is a mailer no service declares yet, with the default attempts: Service.Mailer makes one and declares it, which is how a product gets one.

func NewModule

func NewModule(name string, doc string, parts ...ModuleConfigurer) *Module

NewModule declares a module named name — lower-case letters, digits and dashes, starting with a letter; "kit", "external" and "schema" are kit's — that doc describes, made of parts: its services, which it adopts, the modules it requires (Requires), and the migrations of the data it keeps outside kit's stores (Migrations), run on the database that keeps it. Declare it as a package-level variable of the one package a product imports:

var Module = kit.NewModule("moderation",
	"Reports and moderation under the DSA.\n\nfr: Signalements et modération selon le DSA.",
	intake.Service, desk.Service, kit.Requires(identity.Module))

A service a module lists is its own: what it declared so far is renamed, and what it declares later is born qualified. Listing a service links its package; a service is a module's only, and a module's services take declarations from the module's own Go module only.

func NewPortService

func NewPortService[Req, Resp any]() *PortService[Req, Resp]

NewPortService is a port no service declares yet: Service.Port makes one and declares it, which is how a product gets one.

func NewQuery

func NewQuery[Q, R any]() *Query[Q, R]

NewQuery is a query no service declares yet: Service.Query makes one and declares it, which is how a product gets one.

func NewRecordsService

func NewRecordsService(port recordsPort) RecordsService

NewRecordsService is the records of the store port reaches: App.Records and RecordsOf make one for a store the app mounts.

func NewSecret

func NewSecret() *Secret

NewSecret is a secret no service declares yet, rotated and kept as by default: Service.Secret makes one and declares it, which is how a product gets one.

func NewService

func NewService(name string, doc string) *Service

NewService declares a service. name must be lower-case letters, digits and dashes, starting with a letter; doc is one sentence saying what it owns.

func NewSettingService

func NewSettingService[T SettingValue](def T) *SettingService[T]

NewSettingService is a setting no service declares yet, holding def until something sets it: Service.Setting makes one and declares it, which is how a product gets one.

func NewStoreService

func NewStoreService[T any](key func(T) string) *StoreService[T]

NewStoreService is a store no service declares yet, keying its entities with key: Service.Store makes one and declares it, which is how a product gets one.

func NewTicker

func NewTicker(ctx context.Context, d time.Duration) clock.Ticker

NewTicker is a ticker of period d on the app's clock, for a loop written by hand (Service.Go): a test's manual clock drives it like every timer kit runs itself, where a time.Ticker would tick on the wall clock whatever the test does. It panics on a non-positive d, as time.NewTicker does.

func NewTopicService

func NewTopicService[T any]() *TopicService[T]

NewTopicService is a topic no service declares yet: Service.Topic makes one and declares it, which is how a product gets one.

func NewWorkflowService

func NewWorkflowService[E any, S comparable](store *StoreService[E], state func(*E) *S) *WorkflowService[E, S]

NewWorkflowService is a workflow no service declares yet, over the entities of store whose state state reads: Service.Workflow makes one and declares it, which is how a product gets one.

func NoTransaction

func NoTransaction() CommandConfigurer

NoTransaction runs a command outside a transaction of its own: its writes land as its handler makes them, and its effects leave when made — a failed command may have written or announced something. On the data directory and in memory, where a writing command's transaction takes the writer turn, it lets such commands run side by side. Dispatched inside another command, it still runs in that one's transaction.

func NotCommon

func NotCommon() PasswordConfigurer

NotCommon refuses a password among the ten thousand most common ones — the SDK's password.IsCommon, which compares them without regard to case —: the blocklist NIST SP 800-63B-4 requires a verifier to check, beyond the three thousand OWASP ASVS 5.0 (6.2.4) asks for. Every policy checks it (ADR 0007 §2: on by default once the SDK has the list); the option says so where a policy is declared. Beside NIST's fifteen characters the list has little left to refuse; beside a shorter MinLength, it matters.

IFACE-OPAQUE: the option is sealed — its method is unexported — so a caller only hands it to the declaration it configures.

func NotFound

func NotFound(message string) *Error

NotFound reports that the addressed resource does not exist (404).

func NotReused

func NotReused(n int) PasswordConfigurer

NotReused refuses a password that the current hash, or any of the n former ones, verifies — n from 1 to 100. It is a compliance policy, off by default: PCI DSS asks for it, OWASP ASVS 4.0.3 asks most products not to impose it. kit keeps the field's last n hashes, so it implies history=n, and a tag whose history is smaller than n is refused.

IFACE-OPAQUE: the option is sealed — its method is unexported — so a caller only hands it to the declaration it configures.

func Now

func Now(ctx context.Context) time.Time

Now returns the app's time: the system clock, or the clock a test gave with Clock. Product code that compares with a deadline reads it rather than time.Now, so that a test's manual clock reaches it.

func Optional

func Optional() SecretConfigurer

Optional makes a provided secret one the product can do without — the key of a feature that stays off while nobody gives it. A start where it is set nowhere goes on; Secret.Present says whether it is set now, and a use of it while it is absent — Secret.Value, Seal, Open, Sign or Verify — answers an error errs.HasCode matches with CodeSecretMissing. It is read where it lives at every use, as every provided secret is: given later — `secrets set` in the environment's store, a new content in the file its _FILE variable names —, it is found at its next use. A generated secret is kit's to make and never absent: Optional with Generated is refused.

IFACE-OPAQUE: the option is sealed — its method is unexported — so a caller only hands it to the declaration it configures.

func OwnStores

func OwnStores() SubscriptionConfigurer

OwnStores lets a watch (Service.Watch) hear the stores of its own module too — the product's own, for a watch of the product's —, which a watch never hears by default. Such a watch never hears the writes its own handler makes, in its handler's context — a handler that writes what it watches, a screening that stamps the record it screened, would otherwise hear itself forever —; a write the handler only causes, later and elsewhere — a queued command's handling, a topic's delivery — is heard. A subscription to a topic refuses it: a topic has no stores.

func Parallelism

func Parallelism(n int) DeliveryOption

Parallelism is how many messages are handled at once — a subscription's, or a queued command's. The default is 1.

IFACE-OPAQUE: the option is sealed — its method is unexported — so a caller only hands it to the declaration it configures.

func PerEnv

func PerEnv(name string, fallback string) ScopeValue

PerEnv is the environment variable name, else fallback when it is unset or empty; a leading "/" in either is the user's home directory. The status line's is PerEnv("CLAUDE_CONFIG_DIR", "/.claude"): one daemon per Claude configuration.

func Prefix

func Prefix(prefix string) MountConfigurer

Prefix serves a module's routes under prefix — "/trust/" — instead of "/<module>/"; "/" shares the product's route space, where a route both declare is refused as any two are. A prefix starts and ends with '/', and never lies under /_kit/.

func Profile

func Profile(p string) AppConfigurer

Profile selects the app's process profile: model.ProfileServer (the default), model.ProfileDaemon or model.ProfileCLI.

func Purpose

func Purpose(text string) StoreConfigurer

Purpose says why the store keeps its records (GDPR art. 30(1)(b)): the register lists it, and a person's export carries it.

func Queued

func Queued() CommandConfigurer

Queued sends a command to the background. Dispatch returns once the command's own queue accepted it — a file queue under the data directory, memory without one —, and a consumer handles it, Parallelism at a time, retried up to MaxDeliveries attempts (5) — half a second after the first failure, the wait doubling after each, never more than a minute —, then dead-lettered; a dispatch that does not decode is dead-lettered at its first failure, since no retry makes it decode. It answers nothing: its result is EmptyValue, and exposed, it answers 202 Accepted.

Delivery is at least once: Queued is the product's promise that the handler tolerates a redelivery, and a Command.Key narrows the duplicates without removing them. The handler runs in the dispatcher's trace, as the user who dispatched it (UserID); what the auth handler said about that user is not queued. A queued command's input is a contract with the messages already queued: add a field, never rename one.

func RateLimit

func RateLimit(perSecond float64, burst int) OperationOption

RateLimit puts a token bucket in front of the handler: perSecond tokens a second, up to burst at once. An empty bucket answers 429 at once. It is the SDK's resilience rate limiter.

IFACE-OPAQUE: the option is sealed — its method is unexported — so a caller only hands it to the declaration it configures.

func RateLimitPerClient

func RateLimitPerClient(perSecond float64, burst int) OperationOption

RateLimitPerClient gives every client of an endpoint a token bucket of its own: perSecond tokens a second, up to burst at once. A client is the authenticated user when there is one, and the client's address otherwise (ClientIP); in-process calls through EndpointService.Call share one bucket. One client emptying its bucket is answered 429; the others are not — which is what a sign-in endpoint needs, where one shared bucket would let a single client lock everybody out.

Buckets unused for ten minutes are forgotten, and at most 10 000 are kept: the least recently used goes first. It is the SDK's keyed rate limiter.

IFACE-OPAQUE: the option is sealed — its method is unexported — so a caller only hands it to the declaration it configures.

func ReadModel

func ReadModel() StoreConfigurer

ReadModel marks a store as derived from others (ADR 0005): written by projections — the subscriptions that keep it from the write side's events —, read by queries. It changes nothing of how the store runs; the diagram draws it on its domain's read side, and the static analysis warns of a read model written by anything but a subscription. kit's topics are queues, not logs: a read model cannot be replayed from its events, and one fed by a topic lags the commands that feed it — a query that must read its own writes reads the write side.

var Summaries = Service.Store("summaries", Summary.Key, kit.ReadModel())

func RecordsOf

func RecordsOf(ctx context.Context, store string) (RecordsService, error)

RecordsOf is App.Records for code the app runs and that does not hold it — a module's watch, its endpoints: the records port of the store whose node ID is store, in the app ctx runs in. Outside a running app it is an Unavailable error.

func Screen(ctx context.Context, w kit.Written) error {
	recs, err := kit.RecordsOf(ctx, w.Store)
	…
	record, err := recs.Get(ctx, w.Key)

func RegisterConfigFormat

func RegisterConfigFormat(ext string, format string)

RegisterConfigFormat lets configuration files of extension ext be read with the SDK codec format. framework/kit/config/yaml and config/toml call it as they are imported; a product never does.

func Replace

func Replace[Req, Resp any](op Operation[Req, Resp], fn func(context.Context, Req) (Resp, error)) AppConfigurer

Replace runs fn in place of op's code, in the app it is given to: an endpoint's handler — or, with ADR 0005, a command's or a query's — or what a port calls. It replaces the code, not the mechanics: authentication, decoding, validation and the policies still run, and a replaced port needs no binding, so a module's tests run without a host. fn takes op's request and returns its response, or it does not compile.

A replaced run's span carries mock: replace, and runtime.mocks lists the replacement. It is for tests: the start refuses it in a program go test did not build — neither a production binary nor kit dev can carry one. Given twice for one operation, the last wins.

app := App.With(kit.Replace(apps.AppAPI, func(ctx context.Context, in apps.IDInput) (apps.Profile, error) {
	return apps.Profile{ID: in.AppID}, nil
}))

func Required

func Required() SettingConfigurer

Required drops a setting's default: a start without a value for it fails, saying where to give one.

IFACE-OPAQUE: the option is sealed — its method is unexported — so a caller only hands it to the declaration it configures.

func Requires

func Requires(other *Module) ModuleConfigurer

Requires says the module needs other: an app that mounts the module and not other mounts other at its defaults, and starts it first. The Go import this takes makes a cycle impossible. A collaboration a module can do without is a port with a fallback instead (Fallback).

func RetentionByProduct

func RetentionByProduct(limits string) StoreConfigurer

RetentionByProduct says the product keeps the store's retention itself: its own code erases and deletes what it no longer needs — a record whose life the product's own rules end, a lifecycle kit cannot read from the entity. limits says, in the product's words, for how long and how, which the register publishes as the store's time limits (GDPR art. 30(1)(f)); "" says only that the product keeps them.

kit then runs no retention for the store, and warns of neither a missing retention nor a missing subject. Its classified fields keep every other promise: sealed at rest, never shown, exported with their person — when the store names one — and erased by kit.Erase and Store.Erase. It goes with kit.Purpose, kit.HeldUntil, kit.Anonymise and kit.DeleteOnErasure; with kit.EraseAfter, kit.EraseAt, kit.DeleteAfter or kit.DeleteAt it is refused: a store's retention is kit's or the product's, never both.

func Revisions

func Revisions(n int) StoreConfigurer

Revisions keeps the n previous versions of each record of the store, n from 1 to 100, as WordPress keeps a post's revisions: every write that changes a record makes a version, numbered from 1 and never renumbered, stamped with when it was made, the caller's user and the command that made it; the oldest beyond n are pruned by the write that makes a newer one, unless a legal hold keeps the record.

var Pages = Service.Store("pages", Page.Key, kit.Revisions(20))

revs, err := Pages.Revisions(ctx, id)                            // newest first
edits, err := Pages.Diff(ctx, id, revs[3].Number, revs[0].Number)
page, err := Pages.Restore(ctx, id, revs[3].Number)              // a new version
page, err = Pages.Restore(ctx, id, revs[3].Number, "/title")     // the title only

A store with Revisions(n) holds up to n+1 times its records: in memory with the store in the data directory, in the table <table>___vs on a database, which kit's migrations create.

func Root

func Root(dir string) StaticConfigurer

Root serves the sub-directory dir of the file system rather than its root — "assets" for a //go:embed assets directive.

IFACE-OPAQUE: the option is sealed — its method is unexported — so a caller only hands it to the declaration it configures.

func RotateEvery

func RotateEvery(d time.Duration) SecretConfigurer

RotateEvery is how often kit makes a new version of a generated secret.

IFACE-OPAQUE: the option is sealed — its method is unexported — so a caller only hands it to the declaration it configures.

func ScopeKey

func ScopeKey(scopes ...ScopeValue) (string, error)

ScopeKey is the name the scopes give in this process: 16 hex digits of the SHA-256 of their values. A client computes the key the daemon computed from the same declaration, and so finds its lock or its socket.

func SecretStore

func SecretStore(store secret.Store) AppConfigurer

SecretStore keeps the secrets in store instead of the environment's: a test gives a store holding what its provided secrets hold. The environment's variables are still read first.

func Set

func Set(name string, value any) AppConfigurer

Set gives the setting name a value in code, over the environment and the files: a value of the setting's type, or its text as a variable would hold it. It is for tests.

func SetCookie

func SetCookie(ctx context.Context, c *http.Cookie)

SetCookie adds a Set-Cookie header to the HTTP response of the endpoint ctx serves. kit fills what a cookie left zero with safe defaults — Path "/", HttpOnly, SameSite Lax, and Secure outside dev — so a session cookie is hardened unless the code says otherwise. In an in-process EndpointService.Call there is no response: the cookie is dropped.

HttpOnly is always set, and Secure always outside dev (and in dev for SameSite=None, which browsers require): a boolean has no "unset" a default could fill, and kit chooses the hardened reading. A cookie set more than once in one response keeps its last value, and cookies set before an error are sent with the error — clearing a stale session on a 401 works.

func Singleton

func Singleton(scope string) AppConfigurer

Singleton keeps one process of the app alive per scope on this machine: the start takes an exclusive file lock named after scope in the app's runtime directory (pkg/v1/app/lock: flock, LockFileEx) and holds it until the process ends. A second process refuses to start with CodeSingletonHeld — for a daemon's client, the sign to talk to the one that runs. The kernel drops the lock with a dead process.

func SingletonPer

func SingletonPer(scopes ...ScopeValue) AppConfigurer

SingletonPer keeps one process of the app alive per value of scopes on this machine — per user, per installed executable, per configuration directory (PerUID, PerExecutable, PerConfigDir, PerEnv) —: the lock is named after the scopes' key (ScopeKey), computed at the start, and held as Singleton's is. A client that must find the process computes the same key from the same scopes.

func SocketPath

func SocketPath(path string) ListenerConfigurer

SocketPath places the listener's socket at path — absolute, at most 103 bytes — instead of <runtime dir of the app>/<service>-<name>.sock.

IFACE-OPAQUE: ListenerOption is sealed — its one method is unexported — so only this package makes one, and a caller only passes it to Listen.

func SocketPathFor

func SocketPathFor(product string, service string, name string, scopes ...ScopeValue) (string, error)

SocketPathFor is the socket of the listener name of service in product — the binary's name for a role of one, else the app's —, placed by default and named after scopes (SocketPer): the one rule, for a client of another process role that does not import the daemon's declarations (D22) — it names the three words and the scopes its contract states. The service is its qualified name for a module's.

func SocketPer

func SocketPer(scopes ...ScopeValue) ListenerConfigurer

SocketPer names the listener's socket after the value of scopes in this process — <runtime dir of the app>/<service>-<name>-<key>.sock, the key being ScopeKey's —: one daemon per user, per executable, per configuration directory. A client finds it with SocketPathIn or DialIn, which compute the same key from the same declaration.

IFACE-OPAQUE: ListenerOption is sealed — its one method is unexported — so only this package makes one, and a caller only passes it to Listen.

func Stop

func Stop(ctx context.Context) bool

Stop asks the app ctx runs in to end its run: Run returns as it does on a signal, its stop draining every component — a daemon told "stop" by its client, on its listener, ends itself so. It returns at once, before the stop; it reports false when ctx runs in no app — a handler's, a loop's, a command's context does — or the app does not run.

func Studio

func Studio(on bool) AppConfigurer

Studio switches the Studio on or off in dev. It is always off in production.

func Telemetry

func Telemetry(path string, gids ...int) AppConfigurer

Telemetry exports the app's telemetry on the private socket at path — absolute, and short enough for a Unix socket (pkg/v1/proc/ipc) — admitting the groups gids besides the product's own account. It wins over KIT_TELEMETRY.

func Timeout

func Timeout(d time.Duration) OperationOption

Timeout cancels the handler's context after d and answers 504. It is the SDK's resilience timeout.

IFACE-OPAQUE: the option is sealed — its method is unexported — so a caller only hands it to the declaration it configures.

func Transact

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

Transact runs fn in one transaction and returns fn's error: nil commits what fn wrote, an error undoes it — a panic too, which then continues.

err := kit.Transact(ctx, func(ctx context.Context) error {
	if _, err := Cases.Update(ctx, id, closeCase); err != nil {
		return err // what this function wrote is undone
	}
	if err := Decisions.Insert(ctx, d); err != nil {
		return err
	}
	return Changes.Publish(ctx, Closed{ID: id}) // held: queued at the commit
})

A transaction belongs to one database: the one its first store call reaches — at its first call on a database, at its first write on the data directory, which counts as one, memory with it. Inside it, a store of another database is read as usual; writing one is refused (Invalid, CodeTransactionSpan). A Transact inside another is a savepoint: its failure undoes its own writes, and the outer transaction goes on if its caller handles the error.

What leaves the process waits for the outermost commit: a topic's publish, a queued command's dispatch, a mail — whose outbox ID Mailer.Send returns at once —, a watch's notice, the store's write hooks that wake workflows and loops, a workflow's OnTransition hooks. Each is checked when it is made, so a caller's mistake returns to the caller; a rollback drops them, and a savepoint's rollback its own. A publish, a dispatch, a mail or a notice whose queue lives on the transaction's database — the one that keeps the service of its subscription, command, mailer or watch, by a store's rules — is written in the transaction, just before it commits, a mail sealed under kit's data-key: a queue that refuses it fails the transaction, every write undone, and Transact returns the refusal. Every other one leaves after the commit: one a queue refuses then is logged and reported, and the commit stands; a process that dies between the commit and the release loses what was held.

On a database the transaction is the database's own, at its default isolation. On the data directory and in memory kit keeps its own: it takes the data's writer turn — one transaction at a time; a write outside any waits for it, and such writes share the turn among themselves —, its writes land at once, and an error writes each entity's previous value back, newest first. It is atomic against an error, not against a crash, and a reader may see a write before its commit. A store kept in memory by InMemory — a cache — is in no transaction: its writes land and stay.

A command's handler runs in one already (NoTransaction opts out), and so does a workflow's transition.

func Unauthenticated

func Unauthenticated(message string) *Error

Unauthenticated reports a caller who did not prove who they are (401).

func Unavailable

func Unavailable(message string) *Error

Unavailable reports a transient failure worth retrying later (503).

func Unique

func Unique[T any](name string, key func(T) string) StoreConfigurer

Unique declares a unique index: no two entities may share a key, and a write that would is refused with a Conflict error. An empty key is not indexed. StoreService.Lookup reads it.

var Accounts = Service.Store("accounts", Account.Key,
	kit.Unique("email", func(a Account) string { return a.Email }))

func UserAgent

func UserAgent(ctx context.Context) string

UserAgent returns the User-Agent of the request ctx serves, clipped.

func UserID

func UserID(ctx context.Context) (UID, bool)

UserID returns the authenticated caller of the request ctx serves, and whether there is one. An in-process EndpointService.Call carries its caller's user along.

func WakeAt

func WakeAt(next func(context.Context) (time.Time, bool)) LoopConfigurer

WakeAt wakes the loop at the time next returns, asked again after every run; false means "no deadline for now". It is how a loop sleeps exactly until its next piece of work — the next reminder due — rather than polling.

IFACE-OPAQUE: the option is sealed — its method is unexported — so a caller only hands it to the declaration it configures.

func WakeEvery

func WakeEvery(d time.Duration) LoopConfigurer

WakeEvery wakes the loop every d.

IFACE-OPAQUE: the option is sealed — its method is unexported — so a caller only hands it to the declaration it configures.

func WakeOn

func WakeOn[T any](topic *TopicService[T]) LoopConfigurer

WakeOn wakes the loop whenever a message is published on topic. It is a nudge, not a subscription: the loop is not handed the message and wakes once for a burst — it re-reads the state it works on.

IFACE-OPAQUE: the option is sealed — its method is unexported — so a caller only hands it to the declaration it configures.

func WithUser

func WithUser[D any](ctx context.Context, uid UID, data D) context.Context

WithUser returns ctx acting as the given user, with data: what a job, a loop or a test uses to call an Auth endpoint in-process on someone's behalf.

type ActivityHandler

ActivityHandler is a declared activity of a service: a function that says whether the product is busy. A daemon's IdleStop waits until every activity of its mounted services says false AND no connection is open on its listeners.

type ActivityHandler struct{}

type AnalyzeFunc

AnalyzeFunc reads the product's source — the Go module rooted at dir, and the packages that declare the modules it mounts — into a graph the runtime merges into its own: the edges found in handler bodies, each function's steps. The framework links no analyzer (ADR 0147 §1): the platform's kit tool gives one, in dev, through Analyzer.

type AnalyzeFunc func(ctx context.Context, dir string, modules []string) (*model.Graph, error)

type App

App is the whole product: the services it mounts, served by one process. The same services can be mounted by several apps — one binary per service, or all of them in one — and each app draws exactly what it runs.

type App struct{}

func (App) Fields
func (*App) Fields(m Mark) []FieldRefValue

Fields lists the fields of the app's stores that carry the mark, store by store in the order the app mounts them, each in its entity's order. Personal lists special fields too: they are personal data.

func (App) Graph
func (*App) Graph() *model.Graph

Graph returns the product as a diagram: every node the app mounts with the position of its declaration, the edges that exist by construction, the edges observed at runtime with their counters, and — in dev, once the static analysis has run — the edges found in the handlers' code with their call sites. It is what the Studio draws and what `<app> graph` prints.

func (App) Handler
func (*App) Handler() http.Handler

Handler returns the app's HTTP handler, once started: what httptest wraps.

func (App) Main
func (*App) Main(ctx context.Context, args []string) int

Main is the whole main function of a product:

func main() { os.Exit(App.Main(context.Background(), os.Args[1:])) }

It understands eight commands, so every kit binary can describe itself, be probed, say its configuration, manage its secrets, migrate its databases and answer for the personal data it keeps without a shell or another tool in its image:

serve        run the product (the default)
graph        print the product graph: -format json|mermaid
healthcheck  exit 0 when the product running on KIT_ADDR is ready
config       every setting: its value, never a secret's, and its origin
secrets      list the secrets, set one from standard input, rotate one
migrate      the databases' migrations: status, up, down SET VERSION
privacy      the register of processing, a person's export and erasure,
             the legal holds, the privacy journal, the retention
revisions    a record's version restored

A product's CLI command runs when the first argument names it. A command declared with DefaultCommand runs when the first argument names no command at all — with every argument —, and when there is none, in serve's place: Main then never answers a usage error.

It returns the process exit status rather than exiting, so that deferred work runs and a test can call it.

func (App) Name
func (*App) Name() string

Name returns the product name.

func (App) Records
func (*App) Records(store string) (RecordsService, error)

Records returns the untyped port to the records of the store whose node ID is store: what kit's export and erasure run on, and what a module reads and erases through. A store the app does not mount is a NotFound error.

func (App) Run
func (*App) Run(ctx context.Context) error

Run starts the product, serves until ctx ends or the process receives SIGINT or SIGTERM, then drains it.

Goroutine lifecycle: one goroutine turns a signal into the run's cancellation; it ends when a signal arrives or when the run returns, which cancels the context it also watches.

func (App) Start
func (*App) Start(ctx context.Context) error

Start brings the product up: it checks every declaration, opens the data directory, loads the stores, starts the consumers, the scheduler and the HTTP listener — in that order, through the SDK lifecycle, so a failure unwinds what already started. It returns once the product serves.

func (App) Stop
func (*App) Stop(ctx context.Context) error

Stop drains the product: readiness turns false, then the components stop in reverse order — the HTTP listener finishes its requests before the stores close.

func (App) URL
func (*App) URL() string

URL returns the base URL the app listens on, once started.

func (App) With
func (*App) With(opts ...AppConfigurer) *App

With returns a new app: the same product, with the options of a and then opts — a module among them is mounted. a itself is left as it was, so the options a test gives the product's App — a kit.Set, a kit.Replace — end with that test.

type AppConfigurer

AppConfigurer configures an app. Options win over the environment.

type AppConfigurer interface {
	appConfigure(o *appOptions)
}

type AttrsProvider

AttrsProvider is what the app's auth data says about the caller to the SDK's authz: the attributes Command.Allow and Query.Allow hand a policy — the caller's roles, its groups. Auth data that does not implement it gives none, and every Allow refuses: the start warns of it.

type Me struct{ Roles []string }

func (m Me) Attrs() []authz.Attr { return []authz.Attr{authz.AttrStrings("roles", m.Roles...)} }

kit calls the caller a principal: in kit, a subject is the person personal data is about (ADR 0006).

type AttrsProvider interface {
	Attrs() []authz.Attr
}

func (AttrsProvider) Attrs
func (AttrsProvider) Attrs() []authz.Attr

type AuthenticatorHandler

AuthenticatorHandler is the app's authentication handler: it turns the credentials of a request — a session cookie, a bearer token — into a user, in front of every endpoint declared with Auth or AuthOptional. An app has at most one.

P is the credentials: a struct whose fields are tagged cookie:"…" or header:"…", decoded like an endpoint's request. D is what the handler says about the user; endpoints read it with AuthData.

type AuthenticatorHandler[P, D any] struct{}

type Binary

Binary is one executable the product ships, made of process roles: a status line and its daemon are two roles of one binary, "statusline" and "statusline daemon". Each role is an App — its own services, its own profile — and two roles talk only through a declared, versioned contract (D22): a listener one serves and the other dials, never each other's code.

var Binary = kit.NewBinary("statusline", "The status line of a Claude session.").
	Role("render", RenderApp).                // statusline ...
	Role("daemon", DaemonApp, "daemon").      // statusline daemon ...
	Talks("render", "daemon", "render/v1")

func main() { os.Exit(Binary.Main(context.Background(), os.Args[1:])) }

The package that declares a binary and its roles is wiring, generated from the design (D22).

type Binary struct{}

func (Binary) Main
func (*Binary) Main(ctx context.Context, args []string) int

Main runs the role the arguments select — the one whose args are the longest prefix of them, else the default role — with the rest of the arguments, through its App's Main. It returns the process exit status.

func (Binary) Role
func (*Binary) Role(name string, app *App, args ...string) *Binary

Role adds a process role named name, run by app, selected when the process's first arguments are args; the role without args is the default. It returns b, so roles chain.

func (Binary) Talks
func (*Binary) Talks(from string, to string, contractName string) *Binary

Talks declares that role from talks to role to through contract — "<name>/v<major>". It is the only edge two roles may have.

type CLI

CLI is a short command-line command of the product: it runs once, in the CLI profile, and exits with its status. Main runs it when the process's first argument is its name.

type CLI struct{}

type CLIFunc

CLIFunc is a CLI command's body: its arguments after its name, and the streams; it returns the process exit status (0 success, 64 usage, 70 software — the sysexits a shell script branches on).

type CLIFunc func(ctx context.Context, args []string, std StdioValue) int

type ChangeEvent

ChangeEvent describes one transition, for WorkflowService.OnTransition hooks: the entity, the event, and the states it left and entered.

type ChangeEvent[E any, S comparable] struct {
	// Key is the entity's key in the store.
	Key     string
	// Entity is the entity, as stored after the transition.
	Entity  E
	// Event is the transition's name; "create" for [WorkflowService.Start].
	Event   string
	// From is the state left; the zero S on creation.
	From    S
	// To is the state entered.
	To      S
	// Trigger is "create", "event", "timer" or "guard".
	Trigger string
	// Caller is the node that fired it, when code did.
	Caller  string
	// At is when it happened.
	At      time.Time
}

type Command

Command changes something: a typed input, a typed result, and one handler — the one declared with it. Declare it with Service.Command; dispatch it with Command.Dispatch from any building block, which draws a dispatches edge from the caller; give it a route with Command.Expose. A command is internal until it is exposed: how one service has another change something.

A dispatch runs, in this order: the caller's user when the command asks for one (Auth, implied by Command.Allow) — an in-process dispatch carries its caller's and is not authenticated again —, the input's validate tags, the policies (RateLimit, RateLimitPerClient, Timeout, Bulkhead), the key (Command.Key), the transaction, the authorization (Command.Allow, then Command.Authorize), then the handler. A queued command (Queued) is checked at its dispatch, as its caller — its validate tags, its authorization, its key —, and handled by its queue's consumer, the policies around the handling, its key then its transaction around the handler.

A command is its unit of work (ADR 0004): its authorization and its handler run in one transaction (Transact), opened once its key is held, which holds its effects — a publish, a mail, a queued command's dispatch — until the commit. A failed command changes nothing and announces nothing; one dispatched inside another runs in its transaction. NoTransaction opts a command out.

type Command[C, R any] struct{}

func (Command) Allow
func (*Command) Allow(policy authz.Policy, action string, resource string) *Command[C, R]

Allow makes the command need a permission, as data: the app's policy must let the caller — its user, with the attributes its auth data gives when it implements AttrsProvider — do action to resource. The SDK's authz decides, and closes toward refusal: a role with no grant abstains, and an abstention is refused. Allow implies Auth; given twice, both permissions are needed. The refusal is 403 permission_denied, one sentence whatever the cause.

var PlaceOrder = Service.Command("place-order", placeOrder).Allow(Policy, "place", "order")

func (Command) Authorize
func (*Command) Authorize(fn func(context.Context, C) error) *Command[C, R]

Authorize gives the command a rule that needs the data — the ownership of what the input names, the membership of an organisation: fn sees the input and, through its context, the caller (UserID, AuthData), and returns nil, Forbidden, NotFound — to hide what exists — or an authz.Check of its own. It runs last before the handler, after Command.Allow, under the command's key; its refusal is 403 permission_denied, one sentence whatever the cause, and a NotFound or an Unauthenticated stays what it is. The static analysis reads fn as the command's code: the store it reads is the command's edge.

func (Command) Dispatch
func (*Command) Dispatch(ctx context.Context, in C) (R, error)

Dispatch runs the command for the node ctx runs inside — in a span on the command, its caller's dispatches edge —, through its whole pipeline, and returns its result; a queued command returns once its queue accepted it. The caller's user goes with it.

func (Command) Expose
func (*Command) Expose(route string, opts ...ExposeConfigurer) *Command[C, R]

Expose declares an endpoint that dispatches the command, on route — "METHOD /path/{param}" — with the options an endpoint takes (RateLimitPerClient, MaxBody, Name). It is an endpoint, named after the command — Name for a second exposure —, its request decoded as strictly as any, authenticated when the command asks for a user; the rest — validation, key, authorization — is the command's, so an exposed dispatch and an in-process one are checked alike. It answers 200 with the result, 204 for EmptyValue, 202 for a queued command.

An exposed command says who may run it: a permission (Command.Allow), a rule (Command.Authorize), or, when it declares neither, a marker that it is open on purpose — Anyone, or AnyUser for any signed-in user. The start refuses an exposure that says none of them. A command nobody exposes is internal: the code that needs it dispatches it.

func (Command) Key
func (*Command) Key(fn func(C) string) *Command[C, R]

Key names the entity the command is about: two runs of the command with one key never overlap — the second waits, within its context's deadline —, runs with different keys go at once, and a queued command whose key waits or runs is not queued again until it is handled or dead-lettered. A handler that dispatches its own command with its own key is refused (CodeCommandReentrant), never a deadlock. An input whose key is empty is refused. The key is the span's instance: the Studio filters the runs of one entity.

It is the SDK's lock, in the process: across a restart or between processes, one key can run twice — a handler stays idempotent.

type CommandConfigurer

CommandConfigurer configures a command: Queued; the options every operation takes — Auth, AuthOptional, RateLimit, RateLimitPerClient, Timeout, Bulkhead; and, for a queued one, MaxDeliveries and Parallelism.

type CommandConfigurer interface {
	commandConfigure(o *commandOptions)
}

type CommandLineConfigurer

CommandLineConfigurer tunes a CLI command.

type CommandLineConfigurer interface {
	commandLineConfigure(o *cliOptions)
}

type DatabaseConfigurer

DatabaseConfigurer configures a database: Keeps, Migrations.

type DatabaseConfigurer interface {
	databaseConfigure(o *databaseOptions)
}

type DatabaseURLValue

DatabaseURLValue is what a database's URL points at, as its engine describes it for the graph, the Studio, the logs and every error: never a user, never a password, never a parameter.

type DatabaseURLValue struct {
	// Driver is the Go driver the engine speaks through: "pgx".
	Driver    string
	// Address is where the server listens, host:port; a local socket's
	// path; empty for a file.
	Address   string
	// Database is the database on the server, or the file.
	Database  string
	// TLS is the TLS mode as the URL writes it — "verify-full", "true" —,
	// empty when the URL leaves it to the driver.
	TLS       string
	// Plaintext says the mode the URL writes turns TLS off — sslmode=disable,
	// tls=false —: accepted, for a private network, and drawn "no TLS".
	Plaintext bool
	// Networked says the connection crosses a network, over TCP: outside
	// dev, its URL must write its TLS mode.
	Networked bool
}

type Delay

Delay is how long a timer transition waits: a duration, or a setting that holds one — read when the delay is needed, so each environment can give its own.

type Delay interface {
	time.Duration | *SettingService[time.Duration]
}

type DeliveryOption

DeliveryOption configures a queue's deliveries: a subscription's, or a queued command's (MaxDeliveries, Parallelism).

type DeliveryOption interface {
	SubscriptionConfigurer
	CommandConfigurer
}

type DiagnosticsError

DiagnosticsError is returned by Start when declarations are wrong. It lists every problem at once, each with its position.

type DiagnosticsError struct {
	Diagnostics []model.Diagnostic
}

func (DiagnosticsError) Error
func (*DiagnosticsError) Error() string

Error lists every problem the start found, one per line.

type Edit

Edit is one change between two versions of a record, in RFC 6902's words: Op is add, remove or replace, Path the RFC 6901 JSON pointer of the member it changes, From the value it had and To the value it has, as JSON. A secret member says it changed, never what: its From and To are empty.

type Edit = model.Edit

Edit is an alias of github.com/kitsunium/sdk/framework/model/internal/core.EditMessage, declared as:

type Edit struct {
	Op   string          `json:"op"`
	Path string          `json:"path"`
	From json.RawMessage `json:"from,omitempty" kit:"personal"`
	To   json.RawMessage `json:"to,omitempty" kit:"personal"`
}

type EmptyValue

EmptyValue is the request or the response of an endpoint that has none. An endpoint answering EmptyValue replies 204 No Content.

type EmptyValue struct{}

type EndpointConfigurer

EndpointConfigurer configures an endpoint; each is an ExposeConfigurer too.

type EndpointConfigurer interface {
	endpointConfigure(o *endpointOptions)
	ExposeConfigurer
}

type EndpointService

EndpointService is an HTTP endpoint with a typed request and a typed response: what HTTP itself is about — a webhook a third party calls, say —, the exposure of a command or a query (Command.Expose, Query.Expose), or the implementation of a port (Service.Implement). A business operation is a command or a query, which other code runs with Command.Dispatch and Query.Ask and HTTP reaches through its exposure.

type EndpointService[Req, Resp any] struct{}

func (EndpointService) Call
func (*EndpointService) Call(ctx context.Context, req Req) (Resp, error)

Call runs the endpoint in-process, from another building block: the same validation, the same policies, the same handler, and a calls edge in the diagram from the caller to this endpoint. A port calls its implementation so. Services run each other's operations as commands and queries (Command.Dispatch, Query.Ask); calling a handler function directly works, but the product cannot see it.

type Engine

Engine is an SQL engine a database runs on. An engine module returns one — github.com/kitsunium/sdk/framework/connectors/postgres, …/mysql, …/sqlite —; kit calls it when the database starts. Like an SDK port, it grows by sibling interfaces, never by a method.

type Engine interface {
	// Describe says what url points at — the driver, host and port, the
	// database, the TLS mode as written — for the graph and the logs: never
	// a user, never a password.
	Describe(url secret.Value) (DatabaseURLValue, error)
	// Dialect is the SQL the SDK speaks to it.
	Dialect() sql.Dialect
	// Open opens the pool url names. Before each new connection it asks
	// current for the URL as it is now.
	Open(url secret.Value, current func(context.Context) (secret.Value, error)) (*stdsql.DB, error)
}

func (Engine) Describe
func (Engine) Describe(url secret.Value) (DatabaseURLValue, error)

Describe says what url points at — the driver, host and port, the database, the TLS mode as written — for the graph and the logs: never a user, never a password.

func (Engine) Dialect
func (Engine) Dialect() sql.Dialect

Dialect is the SQL the SDK speaks to it.

func (Engine) Open
func (Engine) Open(url secret.Value, current func(context.Context) (secret.Value, error)) (*stdsql.DB, error)

Open opens the pool url names. Before each new connection it asks current for the URL as it is now.

type Erasure

Erasure is what kit.Erase did, store by store.

type Erasure = model.Erasure

Erasure is an alias of github.com/kitsunium/sdk/framework/model/internal/core.ErasureMessage, declared as:

type Erasure struct {
	// Stores are the stores that kept records about the person.
	Stores []StoreErasureMessage `json:"stores"`
}

type Error

Error is an error a product returns to its callers. Message travels on the wire; the cause attached with Error.Wrap is logged and never sent.

Return one from a handler to choose the HTTP status and the message the caller reads. Any other error becomes a 500 whose body says nothing about it: an error message is the classic place a secret leaks from.

type Error struct {
	// Status is the HTTP status.
	Status     int
	// Code is a stable, snake_case identifier a client can branch on.
	Code       string
	// Message is wire-safe text for the caller.
	Message    string
	// Violations detail an invalid request, one per failed rule.
	Violations []ViolationMessage
}

func (Error) Error
func (*Error) Error() string

Error renders the code and the message. It never renders the cause.

func (Error) Unwrap
func (*Error) Unwrap() error

Unwrap returns the cause, so errors.Is and errors.As see through an Error.

func (Error) Wrap
func (*Error) Wrap(cause error) *Error

Wrap attaches the underlying cause, for the logs. It returns a copy.

type ExposeConfigurer

ExposeConfigurer configures an exposure (Command.Expose, Query.Expose): every EndpointConfigurer — Name, MaxBody, RateLimitPerClient… — and the markers that say who may run an operation declaring no rule of its own: Anyone, AnyUser.

type ExposeConfigurer interface {
	exposeConfigure(o *endpointOptions)
}

type FieldRefValue

FieldRefValue is one field of one store that carries a mark: where the field is, and what its tag says of it.

type FieldRefValue struct {
	// Store is the store's node ID.
	Store   string `json:"store"`
	// Path is the field's JSON pointer in the entity: "/body". A "*"
	// stands for every element of an array or every value of a map:
	// "/replies/*/body".
	Path    string `json:"path"`
	// Class is the field's class; "" when it is unclassified.
	Class   string `json:"class,omitempty"`
	// Subject is the pointer of the store's subject — for moderated
	// content, its author — or "" when the store has none.
	Subject string `json:"subject,omitempty"`
}

type Former

Former is one former value of a field that keeps its history: what it was, until when, and who replaced it.

type Former = model.Former

Former is an alias of github.com/kitsunium/sdk/framework/model/internal/core.FormerMessage, declared as:

type Former struct {
	// Value is the field's value then, as JSON; absent for a secret field,
	// whose former values are never given.
	Value json.RawMessage `json:"value,omitempty" kit:"personal"`
	// Until is when it was replaced, on the app's clock.
	Until time.Time       `json:"until"`
	// By is the user who replaced it — kit.UserID —, empty for a write
	// with no user: a job's, a loop's, kit's own.
	By    string          `json:"by,omitempty"`
}

type Frontend

Frontend is static assets the product serves: a single page application, a documentation site. Requests the page makes to the product's endpoints are attributed to it in the diagram.

type Frontend struct{}

type Job

Job is scheduled work: a piece of the daemon's internal loop. It runs on the SDK scheduler, whose decisions about time are documented rather than emergent: a fire that is due while the previous run of the same job is still going is skipped and counted, and a missed deadline is skipped and counted, never caught up.

type Job struct{}

type Keeper

Keeper is what a database keeps: a service — every store it declares —, a store, or a module (ADR 0008) — every store of its services.

type Keeper interface {
	keep() kept
}

type ListenHandler

ListenHandler serves one connection of a Listener until it returns; the connection is closed after it. conn.Peer says who connected, as the kernel says where it can (pkg/v1/proc/ipc).

type ListenHandler func(ctx context.Context, conn *ipc.Conn) error

type Listener

Listener is an inbound port that is not HTTP: a private socket on this machine — a Unix socket in a directory only the product's account can reach, the kernel naming the peer on Linux (ADR 0148) — speaking a versioned contract. It is how a daemon profile serves its clients, and how two process roles of one binary talk (D22): through the contract, never through each other's code.

type Listener struct{}

func (Listener) Dial
func (*Listener) Dial(ctx context.Context) (*ipc.Conn, error)

Dial connects to the listener as a client of the same account would: the same checks, from the same configuration. A test and a sibling role use it.

func (Listener) DialIn
func (*Listener) DialIn(ctx context.Context, product string) (*ipc.Conn, error)

DialIn connects to the listener as run in product, from another process — a client role of the same binary —: the path SocketPathIn computes, the checks Dial makes.

func (Listener) Path
func (*Listener) Path() string

Path is where the listener listens while the app runs; "" otherwise.

func (Listener) SocketPathIn
func (*Listener) SocketPathIn(product string) (string, error)

SocketPathIn is where the listener's socket lies in product — the binary's name for a role of one, else the app's —: its SocketPath, else <runtime dir of product>/<service>-<name>.sock, with SocketPer's key before the extension. A client of another process role computes the daemon's path with it.

type ListenerConfigurer

ListenerConfigurer tunes a listener.

type ListenerConfigurer interface {
	listenerConfigure(o *listenerOptions)
}

type LockWaiter

LockWaiter is an Engine whose connections wait a bounded time for a lock another connection holds — SQLite's busy timeout —, a sibling of Engine (ADR 0178 C2). kit opens such an engine's pool with OpenWaiting instead of Open, and gives it a wait under <name>-timeout, so that a lost race on the lock comes back as the engine's refusal before the call's own deadline. An engine that does not implement it keeps its own wait.

type LockWaiter interface {
	// OpenWaiting opens the pool url names, as Open does, its connections
	// waiting wait for a lock when url writes no wait of its own.
	OpenWaiting(url secret.Value, current func(context.Context) (secret.Value, error), wait time.Duration) (*stdsql.DB, error)
}

func (LockWaiter) OpenWaiting
func (LockWaiter) OpenWaiting(url secret.Value, current func(context.Context) (secret.Value, error), wait time.Duration) (*stdsql.DB, error)

OpenWaiting opens the pool url names, as Open does, its connections waiting wait for a lock when url writes no wait of its own.

type Loop

Loop is a declared loop of the daemon: kit owns the wait, the product owns the work. Its wake sources — a period, a deadline the product computes, a topic — are data, so the diagram draws exactly what wakes it; kit runs it on its own goroutine, one run at a time, observes every run, and restarts it after a panic.

type Loop struct{}

func (Loop) Nudge
func (*Loop) Nudge()

Nudge wakes the loop now, as if its deadline had come. The run's reason is model.WakeManual; a nudge also cuts short the backoff after a failure. It does nothing while the loop is not running.

type LoopConfigurer

LoopConfigurer configures a declared loop.

type LoopConfigurer interface {
	loopConfigure(o *loopOptions)
}

type Mailer

Mailer is outbound mail: a durable outbox and the transport that empties it. Mailer.Send only queues — it returns once the message is safely in the outbox — and the mailer's own loop hands each message to the transport, retrying a failure and dead-lettering a message after its last attempt.

The transport is the SDK's mail package: SMTP when the mail connector's secret smtp-url is set — KIT_SMTP_URL, smtp://user:password@host:587?tls= starttls|implicit|none — and otherwise the capture transport, which keeps every message for the Studio's mailbox and for tests (Mailer.Captured) and delivers nothing. Outside dev, the capture transport is reported as a warning. The URL is read again before every delivery: replacing it where it lives — a new version in the store, a new file behind KIT_SMTP_URL_FILE — takes effect at the next mail.

type Mailer struct{}

func (Mailer) Captured
func (*Mailer) Captured() []model.MailMessage

Captured returns the messages the capture transport kept, oldest first: what a test reads a verification link from. It is empty with SMTP. A mail appears once the outbox has delivered it — shortly after Send.

func (Mailer) Send
func (*Mailer) Send(ctx context.Context, msg mail.Message) (string, error)

Send validates msg with the SDK's mail rules — a header carrying a line break, an unusable address, an empty body are refused here, not at delivery — and puts it in the outbox. It returns the message's outbox ID. Inside a transaction (Transact, a command's) the mail waits for the commit — a rollback drops it —, and the ID returned at once is the one the mail keeps. When the outbox lives on the transaction's database — the one that keeps the mailer's service, by a store's rules — the mail is written in the transaction, sealed, just before it commits: it exists if and only if the transaction commits, the mailbox hears of it after the commit, and an outbox that refuses it fails the transaction. Elsewhere it is put in the outbox after the commit.

A message without a sender gets the mailer's (From); without a date, the app's time; without a Message-ID, one made of its outbox ID, which every attempt keeps, so a receiver can tell a retried delivery from a new mail.

type MailerConfigurer

MailerConfigurer configures a mailer.

type MailerConfigurer interface {
	mailerConfigure(o *mailerOptions)
}

type Mark

Mark is what a module looks for in the product's fields: kit.Personal, kit.Special or kit.Moderated. There is no mark for public or secret: there is nothing to find in the first, and nothing may watch the second.

type Mark string

type Module

Module is a set of services a product mounts as one: NewModule declares it, App.With or Mount mounts it.

type Module struct{}

func (Module) Name
func (*Module) Name() string

Name returns the module's name.

func (Module) Prefix
func (*Module) Prefix() string

Prefix is where the app running the module serves its routes — "/<name>/" unless the mount says otherwise — and its default before an app runs it. A module's user interface, built with relative URLs, finds its API there.

type ModuleConfigurer

ModuleConfigurer is what a module is made of: its services, the modules it requires (Requires), and the migrations of the data it keeps outside kit's stores (Migrations).

type ModuleConfigurer interface {
	moduleConfigure(m *Module)
}

type MountConfigurer

MountConfigurer configures the mount of a module: Prefix, Bind.

type MountConfigurer interface {
	mountConfigure(d *mountDecl)
}

type Operation

Operation takes a typed request and answers a typed response: an endpoint, a port — and, with ADR 0005, a command or a query. It is what Fallback and Bind give a port, and what Replace replaces in a test; a request or a response of other types does not compile. Its methods are unexported: only kit implements it.

Every operation is a node of the graph, and runs in a span of its own through its whole pipeline — authentication, validation, policies, the Studio's mocks — whoever calls it.

type Operation[Req, Resp any] interface {
	edgeKind() model.EdgeKind
	perform(ctx context.Context, req Req) (Resp, error)
	node
}

type OperationOption

OperationOption configures an endpoint, a command or a query alike: the authentication it asks for (Auth, AuthOptional) and the policies in front of its handler (RateLimit, RateLimitPerClient, Timeout, Bulkhead).

type OperationOption interface {
	EndpointConfigurer
	CommandConfigurer
	QueryConfigurer
}

type PasswordConfigurer

PasswordConfigurer configures a password policy: MinLength, NotReused, NotCommon.

type PasswordConfigurer interface {
	passwordConfigure(o *passwordOptions)
}

type PasswordPolicyService

PasswordPolicyService is the policy of one secret field that holds a password's hash: how long a password is at least, and how many former passwords it refuses. StoreService.Passwords declares it; Set, Change and Verify apply it.

type PasswordPolicyService[T any] struct{}

func (PasswordPolicyService) Change
func (*PasswordPolicyService) Change(ctx context.Context, key string, current []byte, next []byte) error

Change changes the password of the record under key: it verifies the current password first, as Symfony's UserPassword does — a wrong one is an Invalid error —, then sets next as Set does.

func (PasswordPolicyService) Set
func (*PasswordPolicyService) Set(ctx context.Context, key string, password []byte) error

Set sets the password of the record under key — a reset flow, behind a reset token: it checks the policy — the length, the most common passwords, and with NotReused the former passwords —, hashes the password with the SDK's password.Hash and stores the hash; the hash it replaces goes to the field's history. A password the policy refuses is an Invalid error, which says it was used recently, never which one; a missing record is a NotFound.

func (PasswordPolicyService) Verify
func (*PasswordPolicyService) Verify(ctx context.Context, key string, password []byte) (bool, error)

Verify reports whether password is the one of the record under key, for a login, with the SDK's constant-time Verify. When the stored hash is weaker than the SDK's policy now (password.NeedsRehash), kit stores it again, hashed anew: the same password, so no former value. A key with no record — or a record with no password yet — costs what a wrong password costs, and answers false.

type PersonalData

PersonalData is a person's data as kit.Export gives it.

type PersonalData = model.PersonalData

PersonalData is an alias of github.com/kitsunium/sdk/framework/model/internal/core.PersonalDataMessage, declared as:

type PersonalData struct {
	// Stores are the stores that keep records about the person.
	Stores []StoreDataMessage `json:"stores"`
}

type PortConfigurer

PortConfigurer configures a port: Fallback.

type PortConfigurer[Req, Resp any] interface {
	portConfigure(p *PortService[Req, Resp])
}

type PortService

PortService is an operation a service needs and does not implement: a typed request, a typed response, a name. Declare it with Service.Port, and call it with PortService.Call as an endpoint is called: validated, observed, drawn.

What a port calls is decided when the app starts, by one rule the static analysis shares: the app's Bind, else the one Service.Implement among the services the app mounts, else the port's own Fallback. The start refuses a port it cannot bind, with every other problem at once.

A port is how a service reaches what it cannot import — a module its host's content, a service another that imports it — the consumer owning the contract.

type PortService[Req, Resp any] struct{}

func (PortService) Call
func (*PortService) Call(ctx context.Context, req Req) (Resp, error)

Call runs what the port is bound to: in a span on the port — the caller's calls edge — then in the bound operation's own span, through its whole pipeline, carrying the caller's user as EndpointService.Call does.

type Query

Query reads and changes nothing: a typed input, a typed result, and one handler — the one declared with it. Declare it with Service.Query; ask it with Query.Ask from any building block, which draws an asks edge from the caller; give it a route with Query.Expose. A query is internal until it is exposed: how one service reads what another keeps. The static analysis warns of a query whose code writes a store, fires a workflow, publishes, sends a mail or dispatches a command.

A question runs, in this order: the caller's user when the query asks for one (Auth, implied by Query.Allow), the input's validate tags, the policies, the authorization (Query.Allow, then Query.Authorize), then the handler, on the caller's goroutine.

type Query[Q, R any] struct{}

func (Query) Allow
func (*Query) Allow(policy authz.Policy, action string, resource string) *Query[Q, R]

Allow makes the query need a permission, as data: the app's policy must let the caller — its user, with the attributes its auth data gives when it implements AttrsProvider — do action to resource. It implies Auth; given twice, both permissions are needed. The refusal is 403 permission_denied, one sentence whatever the cause.

func (Query) Ask
func (*Query) Ask(ctx context.Context, in Q) (R, error)

Ask runs the query for the node ctx runs inside — in a span on the query, its caller's asks edge —, through its whole pipeline, and returns its result. The caller's user goes with it.

func (Query) Authorize
func (*Query) Authorize(fn func(context.Context, Q) error) *Query[Q, R]

Authorize gives the query a rule that needs the data: fn sees the input and, through its context, the caller, and returns nil, Forbidden, NotFound — to hide what exists — or an authz.Check of its own. It runs last before the handler, after Query.Allow; its refusal is 403 permission_denied, one sentence whatever the cause, and a NotFound or an Unauthenticated stays what it is.

func (Query) Expose
func (*Query) Expose(route string, opts ...ExposeConfigurer) *Query[Q, R]

Expose declares an endpoint that asks the query, on route, with the options an endpoint takes (RateLimitPerClient, MaxBody, Name): named after the query, authenticated when the query asks for a user, the rest of the pipeline the query's. It answers 200 with the result, 204 for EmptyValue.

An exposed query says who may ask it: a permission (Query.Allow), a rule (Query.Authorize), or, when it declares neither, a marker that it is open on purpose — Anyone, or AnyUser for any signed-in user. The start refuses an exposure that says none of them. A query nobody exposes is internal: the code that needs it asks it.

type QueryConfigurer

QueryConfigurer configures a query: the options every operation takes — Auth, AuthOptional, RateLimit, RateLimitPerClient, Timeout, Bulkhead.

type QueryConfigurer interface {
	queryConfigure(o *queryOptions)
}

type RecordsService

RecordsService is one store's records without their type. Get returns a record without its secret members; Keys lists the records' keys, to a module that watches the store; EraseFields and Delete take a reason and are refused on a held record. Each call is a span on the store's node and an entry in the privacy journal.

type RecordsService struct{}

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

Delete removes the record under key; a held record is a Conflict.

func (RecordsService) EraseFields
func (RecordsService) EraseFields(ctx context.Context, key string, reason string, paths ...string) error

EraseFields clears the fields at paths — pointers as FieldRefValue gives them — in the record under key: the final removal of a moderated field. A path that names no classified field is an Invalid error; a held record is a Conflict.

func (RecordsService) Get
func (RecordsService) Get(ctx context.Context, key string) (json.RawMessage, error)

Get returns the record under key as JSON, its secret members left out.

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

Keys yields the key of every record the store holds, in key order, and nothing of a record: what a watch reads to catch up on the writes it may have missed. It is offered only to a module one of whose watches the store feeds — any other caller, code outside a module's node included, is refused with a Forbidden error (CodeRecordsKeys) —, and each listing is one entry in the privacy journal, however many keys it yields. A record in the store's trash is not listed. A failure is yielded once, with an empty key, and ends the listing.

type RevisionEvent

RevisionEvent is one version of a record a store with Revisions keeps: its number — from 1, never given twice while the record exists —, when the write that made it ran, on the app's clock, zero for a record stored before its store kept revisions; who made it — the caller's UserID, empty for a write with no user —; which command made it — its node ID, empty outside a command —; and the record as it was, its secret members zeroed.

type RevisionEvent[T any] struct {
	Number  uint64
	At      time.Time
	By      string
	Command string
	Value   T
}

type Routine

Routine is a loop written by hand: a function that runs until its context ends. kit starts it with the app, cancels its context on shutdown and waits for it, restarts it after an error or a panic — backing off from one second to one minute — and reads its select statements to draw what it waits on.

type Routine struct{}

type ScopeValue

ScopeValue is one part of a path computed at the start: the user, the executable, a configuration directory. Two processes share a singleton or a socket when every scope gives them the same value.

type ScopeValue struct{}

type Secret

Secret is a secret the product declares: provided by the operator — an SMTP URL, an API token — or generated by kit — a signing or sealing key — and rotated on its schedule.

type Secret struct{}

func (Secret) Open
func (*Secret) Open(ctx context.Context, box []byte, aad []byte) ([]byte, error)

Open decrypts a box any kept version sealed, with the aad it was sealed with. A box no kept version opens — forged, altered, or sealed by a version pruned since — is refused with an error errors.Is matches with secret.SealInvalid.

func (Secret) Present
func (*Secret) Present(ctx context.Context) (bool, error)

Present reports whether the secret is set now, where it lives: false, and no error, when an Optional secret is given nowhere — which the product answers by leaving off what needs it. An error says its store could not be read. A secret the start required is present, unless the operator took it back since.

if ok, err := OpenAIKey.Present(ctx); err != nil || !ok {
	return Verdict{}, err // no key, no automatic screening
}

func (Secret) Seal
func (*Secret) Seal(ctx context.Context, plaintext []byte, aad []byte) ([]byte, error)

Seal encrypts plaintext under the secret's current version, binding aad: data that travels beside the box in the clear and must come back unchanged for the box to open.

func (Secret) Sign
func (*Secret) Sign(ctx context.Context, message []byte) ([]byte, error)

Sign signs message with the secret's current version.

func (Secret) Value
func (*Secret) Value(ctx context.Context) (secret.Value, error)

Value returns the secret's current version. A provided secret is read where it lives at every call.

func (Secret) Verify
func (*Secret) Verify(ctx context.Context, message []byte, signature []byte) error

Verify reports whether a kept version signed message: nil when one did, and an error errors.Is matches with secret.SignatureInvalid when none did.

type SecretConfigurer

SecretConfigurer configures a secret.

type SecretConfigurer interface {
	secretConfigure(o *secretOptions)
}

type Service

Service is a bounded context of the product: it owns its building blocks — endpoints, stores, topics, subscriptions, workflows, jobs, frontends — and is the unit an App mounts. Declare one per package, as a package-level variable, and declare its building blocks through its methods:

var Service = kit.NewService("todos", "The todo list.")
var Todos = Service.Store("todos", func(t Todo) string { return t.ID })
var _ = Service.Endpoint("GET /todos", List)

Declaring never fails: a mistake — a malformed route, a duplicate name — is recorded with its source position and reported, all at once, when the App starts. The diagram shows it too.

type Service struct{}

func (Service) Activity
func (*Service) Activity(fn func(context.Context) bool) *ActivityHandler

Activity declares that the service is busy while fn returns true: a daemon whose clients are sessions, not connections, stops once the last session ended rather than once the last connection closed. fn is called on the idle watch's tick, from one goroutine, and must answer quickly; a panic counts as busy, and is logged. The value is kept for the declaration:

var _ = Service.Activity(func(context.Context) bool { return sessions.Open() > 0 })

func (Service) AuthHandler
func (*Service) AuthHandler[P, D any](name string, handler func(context.Context, P) (UID, D, error)) *AuthenticatorHandler[P, D]

AuthHandler declares the app's authentication handler. The handler returns the user's ID and data; an empty UID with a nil error means "no credentials", which Auth endpoints answer 401 and AuthOptional endpoints serve anonymously; an error — usually Unauthenticated — refuses the request.

The handler runs only for a request that carries at least one of the credentials' cookies or headers; a request with none is anonymous without asking it.

func (Service) CLI
func (*Service) CLI(name string, doc string, fn CLIFunc, opts ...CommandLineConfigurer) *CLI

CLI declares a command named name, which Main runs when the process is called "<binary> <name> ...". doc is its one-line help.

func (Service) Command
func (*Service) Command[C, R any](name string, handler func(context.Context, C) (R, error), opts ...CommandConfigurer) *Command[C, R]

Command declares a command of the service: an operation named name, run by handler, that changes something. Its node is "<service>/command/<name>".

var PlaceOrder = Service.Command("place-order", placeOrder).
	Allow(Policy, "place", "order").
	Expose("POST /orders")

func (Service) Cron
func (*Service) Cron(name string, expr string, fn func(context.Context) error) *Job

Cron declares a job that runs on a five-field POSIX cron expression, in the process's local time zone.

func (Service) Endpoint
func (*Service) Endpoint[Req, Resp any](route string, handler func(context.Context, Req) (Resp, error), opts ...EndpointConfigurer) *EndpointService[Req, Resp]

Endpoint declares an HTTP endpoint on route — "METHOD /path/{param}" — run by handler. The request is decoded from the path, the query, the headers (fields tagged `path:"…"`, `query:"…"`, `header:"…"`) and the JSON body (every other field), then checked against its `validate` tags, then handed to the policies (RateLimit, Timeout, Bulkhead) and the handler. The response is JSON, or 204 No Content when it is EmptyValue.

An endpoint is for what HTTP itself is about — a webhook a third party calls. A business operation is a command or a query, exposed on its route (Command.Expose, Query.Expose), and run in process by the code that needs it (Command.Dispatch, Query.Ask).

The endpoint's name, and so its node ID, is the handler's function name.

func (Service) Every
func (*Service) Every(name string, period time.Duration, fn func(context.Context) error) *Job

Every declares a job that runs every period, first one period after the app starts.

func (Service) Go
func (*Service) Go(name string, run func(context.Context) error) *Routine

Go declares a hand-written loop. run must return when ctx ends; returning earlier, with or without an error, restarts it after a backoff.

Everything run does is drawn from the loop's node: a store it reads, a topic it publishes on. kit has no span around it — a run lasts as long as the app — so each of those calls starts a trace of its own.

func (Service) Implement
func (*Service) Implement[Req, Resp any](port *PortService[Req, Resp], handler func(context.Context, Req) (Resp, error), opts ...EndpointConfigurer) *EndpointService[Req, Resp]

Implement declares that the service implements port: an endpoint of the service with no route, which only the port reaches, in process, when the app binds nothing else and this is the one implementation among the services it mounts. It runs as every endpoint does — the request's validate tags, the options' policies, the caller's user — and is named like one: its Name, else its handler's name, else, for a function literal, the port's name. A handler whose request or response is not the port's does not compile. A host implements a module's port on its own service: it never adds a node to the module's.

var _ = posts.Service.Implement(desk.Enforcer, Enforce)

func (Service) Listen
func (*Service) Listen(name string, contract string, handler ListenHandler, opts ...ListenerConfigurer) *Listener

Listen declares a listener named name speaking contract — "<name>/v<major>", "render/v1" — whose connections handler serves, one goroutine each.

func (Service) Loop
func (*Service) Loop(name string, run func(context.Context, WakeEvent) error, opts ...LoopConfigurer) *Loop

Loop declares a loop run by kit: run is called once at start, then on every wake.

Runs never overlap: wakes that come while the function runs are gathered into one run after it. A run that fails or panics is counted, and the next one waits a backoff — one second, doubling up to a minute — unless it is a Loop.Nudge. A deadline already past wakes the loop at once, but never sooner than a second after the previous run: a WakeAt that keeps answering the past costs a run a second, not a spinning core.

func (Service) Mailer
func (*Service) Mailer(name string, opts ...MailerConfigurer) *Mailer

Mailer declares outbound mail.

func (Service) Name
func (*Service) Name() string

Name returns the service name, which is also its node ID: qualified with its module's, "moderation.intake", when a module lists it.

func (Service) Port
func (*Service) Port[Req, Resp any](name string, opts ...PortConfigurer[Req, Resp]) *PortService[Req, Resp]

Port declares a port of the service: an operation it needs, named name, taking Req and answering Resp, which another service implements (Service.Implement) or the app binds (Bind). Its node is "<service>/port/<name>"; its doc is its declaration's doc comment.

func (Service) Query
func (*Service) Query[Q, R any](name string, handler func(context.Context, Q) (R, error), opts ...QueryConfigurer) *Query[Q, R]

Query declares a query of the service: an operation named name, run by handler, that reads and changes nothing. Its node is "<service>/query/<name>".

var MyOrders = Service.Query("my-orders", myOrders, kit.Auth()).Expose("GET /orders", kit.AnyUser())

func (Service) Secret
func (*Service) Secret(name string, opts ...SecretConfigurer) *Secret

Secret declares a secret the product needs.

Without an option it is provided: the operator gives it in the environment — the variable <APP>_<NAME>, TODO_STRIPE_KEY for the secret "stripe-key" of the app "todo", or TODO_STRIPE_KEY_FILE naming a file that holds it, the Docker and Kubernetes way — or in the environment's store, with `kit secrets set`. It is read at every use, so replacing it where it lives takes effect without a restart, and a start without it fails, naming the variable to set.

With Optional, a start without it goes on: the product asks Secret.Present before it uses the secret.

With Generated, kit makes it: version 1 on the first start, a new version on its schedule, the previous ones kept so that what they sealed or signed still opens and verifies. It lives in the store the environment keeps — an encrypted file store in dev, KIT_SECRETS elsewhere. Its variable pins it: kit then uses the value as it is and does not rotate it.

name is 1 to 63 lower-case letters, digits and dashes, starting and ending with a letter or a digit — one grammar for a file name and a variable — and unique in the app.

func (Service) Setting
func (*Service) Setting[T SettingValue](name string, def T, opts ...SettingConfigurer) *SettingService[T]

Setting declares a setting of the service: name holds def unless the environment says otherwise — the variable <APP>_<NAME>, TODO_BASE_URL for the setting "base-url" of the app "todo", or the key name in the product's configuration files. SettingService.Get reads it.

name follows the secrets' grammar — 1 to 63 lower-case letters, digits and dashes, starting and ending with a letter or a digit — and is unique in the app, among its settings and its secrets: the two share their variables.

func (Service) Static
func (*Service) Static(name string, prefix string, fsys fs.FS, opts ...StaticConfigurer) *Frontend

Static declares a frontend serving fsys under prefix, which must end with '/'. A path with no file extension that matches no file serves index.html, so client-side routing works; a missing file with an extension — a script, a stylesheet — stays a 404. A directory is never listed. The SDK's static handler serves it; kit draws it and observes every request.

func (Service) Store
func (*Service) Store[T any](name string, key func(T) string, opts ...StoreConfigurer) *StoreService[T]

Store declares a store of entities of type T, keyed by key.

func (Service) Subscribe
func (*Service) Subscribe[T any](name string, topic *TopicService[T], handler func(context.Context, T) error, opts ...SubscriptionConfigurer) *SubscriptionWorker[T]

Subscribe declares a subscription of the service to topic. Delivery is at least once: handler must be idempotent, which is the one thing the SDK's queue cannot check and kit therefore asks you to promise here.

func (Service) Topic
func (*Service) Topic[T any](name string) *TopicService[T]

Topic declares a topic carrying messages of type T.

func (Service) Watch
func (*Service) Watch(name string, mark Mark, handler func(context.Context, WrittenEvent) error, opts ...SubscriptionConfigurer) *Watch

Watch declares a watch of the service: handler is told of every write kit confirms on a store whose entity holds a field that carries mark — the product's stores and the other modules', never those of the module the service belongs to (for a service of the product's, never the product's own) unless OwnStores says so. The notice says which store, which record and whether it was deleted; the handler reads the record itself (RecordsOf). Delivery is at least once and in no set order, retried and dead-lettered after MaxDeliveries attempts: handler must be idempotent, and it hears the writes it makes itself on another's store — with OwnStores, never a write its own handler makes. After a stop that was not clean — the process died with the watch running —, its next start queues a notice for every record of every store that feeds it, so that no write a crash took the notice of goes unheard; a deletion whose notice was lost is not among them. The mark that says a watch runs is kept in the data directory: an app without one does not catch up (ADR 0178 C6).

var Content = Service.Watch("content", kit.Moderated, Screen)
var Posts = Service.Watch("posts", kit.Moderated, Stamp, kit.OwnStores())

func (Service) Workflow
func (*Service) Workflow[E any, S comparable](name string, store *StoreService[E], state func(*E) *S) *WorkflowService[E, S]

Workflow declares a state machine over the entities of store. state returns a pointer to the entity's state field.

type SettingConfigurer

SettingConfigurer configures a setting.

type SettingConfigurer interface {
	settingConfigure(o *settingBase)
}

type SettingService

SettingService is a value the environment gives a service, declared with Service.Setting.

type SettingService[T SettingValue] struct{}

func (SettingService) Get
func (*SettingService) Get() T

Get returns the setting's value in the app the service is mounted in — its default until an app has started with it.

func (SettingService) Name
func (*SettingService) Name() string

Name is the setting's name, its key in a configuration file — in its module's section, for a module's setting.

type SettingValue

SettingValue is what a setting may hold.

type SettingValue interface {
	string | bool | int | int64 | float64 | time.Duration | []string
}

type StaticConfigurer

StaticConfigurer configures a frontend.

type StaticConfigurer interface {
	staticConfigure(o *staticOptions)
}

type StdioValue

StdioValue is where a CLI command reads and writes: the process's own streams under Main, buffers in a test.

type StdioValue struct {
	// In is the command's standard input.
	In          io.Reader
	// Out and Err are its standard output and error.
	Out         io.Writer
	// Out and Err are its standard output and error.
	Err         io.Writer
	// Interactive reports whether In is a terminal.
	Interactive bool
}

type StoreConfigurer

StoreConfigurer configures a store.

type StoreConfigurer interface {
	storeConfigure(o *storeOptions)
}

type StoreService

StoreService is a typed, keyed collection of entities. Every read returns a copy and every write stores one: an entity is kept as its JSON encoding, so what a handler holds can never alias what the store holds, and the memory and file backends behave identically.

With a data directory (KIT_DATA_DIR; ".kit/data" in dev) the store persists every write before returning, atomically — a crash never leaves a torn file — and a write costs one entity, whatever the store holds. Without one, it lives in memory. A store a database keeps (Database, Keeps) lives in a table of it, and every call is a round trip. A store is a port (ADR 0004): what it runs on is its engine (store_engine.go) — the SDK's document store, in memory, in files or over SQL —; kit makes it a node of the graph, observes every call, and speaks for its refusals. Its writes join the transaction their context carries (Transact).

type StoreService[T any] struct{}

func (StoreService) Count
func (*StoreService) Count(ctx context.Context) (int, error)

Count returns how many entities the store holds.

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

Delete removes the entity with the given key, or returns a NotFound error. When the store seals at rest and the entity was its person's last record, their data key goes with it, as with an erasure — at the commit, in a Transact —, once nothing kit keeps still needs it: a held record, or a former value or version sealed under it, keeps the key.

func (StoreService) Diff
func (*StoreService) Diff(ctx context.Context, key string, from uint64, to uint64) ([]Edit, error)

Diff returns what changed from the version numbered from to the version numbered to of the record under key, in RFC 6902's words — add, remove, replace, each at a JSON pointer — with both values, in the order they apply: none when the two are the same. A secret member says it changed, never what. Showing a text's changes line by line is the reader's: the Studio does it.

func (StoreService) Erase
func (*StoreService) Erase(ctx context.Context, key string, reason string) error

Erase erases one record now, as its retention would: its personal, special and secret members and its subject cleared — after the store's Anonymise function has kept what it generalises —, its erased fields stamped, the rest kept. A held record is refused with a Conflict that names the hold, never a placed hold's reason. reason is journaled, for whoever runs the product.

func (StoreService) Filter
func (*StoreService) Filter(ctx context.Context, keep func(T) bool) ([]T, error)

Filter returns the entities keep accepts, ordered by key. It reads every entity: an index is the way to avoid it.

func (StoreService) Find
func (*StoreService) Find(ctx context.Context, index string, key string) ([]T, error)

Find returns the entities indexed under key, ordered by their store key. It reads any index, unique or not; no entity is an empty slice, not an error.

func (StoreService) Former
func (*StoreService) Former(ctx context.Context, key string, pointer string) ([]Former, error)

Former returns the former values of the field at pointer — its JSON pointer (RFC 6901), "/email" — in the record under key, newest first: each with when it was replaced and by whom. A secret field's former values say when they changed, never what they were: their Value is empty. A field that keeps no former values is an Invalid error, a missing record a NotFound.

func (StoreService) Get
func (*StoreService) Get(ctx context.Context, key string) (T, error)

Get returns the entity with the given key, or a NotFound error.

func (StoreService) Hold
func (*StoreService) Hold(ctx context.Context, key string, reason string) error

Hold places a legal hold on the record under key: neither the retention, nor a person's erasure, nor Delete touches it until StoreService.Release lifts it. reason says why — an authority's request, a case under litigation — and is kept for whoever runs the product, never shown in the Studio. Holding a held record again replaces its reason.

func (StoreService) Insert
func (*StoreService) Insert(ctx context.Context, v T) error

Insert stores a new entity; it is a Conflict error when the key exists.

func (StoreService) List
func (*StoreService) List(ctx context.Context) ([]T, error)

List returns every entity, ordered by key.

func (StoreService) Lookup
func (*StoreService) Lookup(ctx context.Context, index string, key string) (T, error)

Lookup returns the entity whose key in the unique index is key, or a NotFound error. Asking a non-unique index is an Invalid error: use StoreService.Find.

func (StoreService) Passwords
func (*StoreService) Passwords(field func(*T) *string, opts ...PasswordConfigurer) *PasswordPolicyService[T]

Passwords declares the password policy of one secret field of the store's entity; field names it — kit calls it on a zero entity to find which. The field then only ever holds the password's hash, a PHC string, or nothing before a first password; a write that puts anything else in it is refused. A field that is not secret refuses the start, as does a second policy on the same field.

func (StoreService) Put
func (*StoreService) Put(ctx context.Context, v T) error

Put stores the entity, replacing any entity with the same key.

func (StoreService) Release
func (*StoreService) Release(ctx context.Context, key string) error

Release lifts the hold on the record under key: the retention takes it up again, from where its instants say. A record no hold keeps is a NotFound error.

func (StoreService) Restore
func (*StoreService) Restore(ctx context.Context, key string, number uint64, fields ...string) (T, error)

Restore writes the version numbered number of the record under key back, as a new version: history is never rewritten. It restores the whole version, or only the fields named by JSON pointer (RFC 6901) — "/title" —, as WordPress restores some fields of a revision. It keeps the record's workflow state, which its workflow owns, and every secret member: restoring an account never brings back an old password past its policy, and naming one of them is an Invalid error. A unique index the restored record breaks refuses it with a Conflict, and nothing changes. It returns the record as restored.

func (StoreService) Revision
func (*StoreService) Revision(ctx context.Context, key string, number uint64) (RevisionEvent[T], error)

Revision returns the version numbered number of the record under key, its secret members zeroed: a NotFound when the record keeps none of that number — never made, or pruned.

func (StoreService) Revisions
func (*StoreService) Revisions(ctx context.Context, key string) ([]RevisionEvent[T], error)

Revisions returns the versions the store keeps of the record under key, newest first: the record as it is now, then the former ones — n at most, more while a legal hold keeps the record. A secret member is zeroed in each: a former password hash never reaches the product. A missing record is a NotFound, a store that keeps no revisions an Invalid.

func (StoreService) Update
func (*StoreService) Update(ctx context.Context, key string, fn func(*T) error) (T, error)

Update applies fn to the entity with the given key and stores the result, atomically with respect to every other write of this store. fn must not change the key. An error from fn leaves the entity untouched.

fn runs while the store's writers wait — on a database, inside the write's transaction, the entity locked —: it may read this store, but must not write to it, nor fire a workflow over it — either would wait for the write fn is part of.

type SubscriptionConfigurer

SubscriptionConfigurer configures a subscription.

type SubscriptionConfigurer interface {
	subscriptionConfigure(o *subscriptionOptions)
}

type SubscriptionWorker

SubscriptionWorker consumes a topic: its handler runs once per message, at least once, retried on error, and dead-lettered after MaxDeliveries attempts.

type SubscriptionWorker[T any] struct{}

type TopicService

TopicService is an asynchronous channel of messages of type T. Every subscription receives every message, at least once: a subscription's handler must tolerate a redelivery.

type TopicService[T any] struct{}

func (TopicService) Publish
func (*TopicService) Publish(ctx context.Context, msg T) error

Publish sends msg to every subscription. It returns once every subscription's queue has accepted the message; delivery happens later. Inside a transaction (Transact, a command's) the message is encoded now and queued at the commit: in the transaction, just before it commits, for a subscription whose queue lives on the transaction's database — a queue that refuses it then fails the transaction —, once it committed for the others. A rollback drops it.

type UID

UID identifies an authenticated user. It is what the auth handler returns and what every endpoint reads with UserID.

type UID string

type ViolationMessage

ViolationMessage is one validation rule a request failed: where, which rule, and why — never the value.

type ViolationMessage struct {
	// Path locates the value: "title", "items[2].zip".
	Path    string `json:"path"`
	// Rule names the failed rule: "required", "maxlen".
	Rule    string `json:"rule"`
	// Message explains it without echoing the value.
	Message string `json:"message"`
}

type WakeEvent

WakeEvent says why a declared loop runs: the reason, the instant, and the topic that woke it when one did. Wakes that come while it runs, or while it backs off after a failure, are gathered into one run: Reasons and Topics say every one of them, and Reason the one that decides the run.

type WakeEvent struct {
	// Reason is model.WakeInterval, WakeDeadline, WakeTopic, WakeStart or
	// WakeManual: WakeManual when a nudge is among the wakes the run
	// gathers — the one wake that cuts a backoff short —, else the first
	// that came.
	Reason  string
	// At is when the wake happened, on the app's clock.
	At      time.Time
	// Topic is the topic node whose publish woke the loop first, when a
	// topic's did.
	Topic   string
	// Reasons are the reasons of every wake the run gathers, each once, in
	// the order they came: Reason is among them.
	Reasons []string
	// Topics are the topic nodes whose publish woke the loop into this run,
	// each once, in the order they came: Topic is the first.
	Topics  []string
}

type Watch

Watch is a subscription fed by stores instead of a topic: its handler is told of every write kit confirms on a store whose entity holds a field with its mark. Service.Watch declares one.

type Watch struct{}

type WorkflowService

WorkflowService is a state machine over the entities of one store: the states an entity goes through, and the arrows between them. It is declared as data — which is why the diagram can draw it exactly — and it runs four kinds of transitions:

The SDK's state-machine engine runs it (statemachine). Its loop never polls: it keeps an agenda of the transitions due, sleeps until the earliest, and a write of the store — which may bring one forward — wakes it. A workflow with nothing due does not run at all. Transitions of one entity run one at a time, of different entities at once.

The entity's state lives in the entity itself (the state function returns a pointer to it), so the store stays the single source of truth; the engine keeps, beside it, when each entity entered its state and the history of its transitions — in the workflow's file under the data directory, so a timer keeps counting across a restart.

type WorkflowService[E any, S comparable] struct{}

func (WorkflowService) After
func (*WorkflowService) After[D Delay](event string, d D, from S, to S) *WorkflowService[E, S]

After declares a timer transition: an entity that has spent d in state from moves to state to, fired by the workflow's own loop. d is a duration, or a setting of the service that holds one — which must then be positive.

func (WorkflowService) At
func (*WorkflowService) At(event string, from S, to S, instant func(E) (time.Time, bool)) *WorkflowService[E, S]

At declares a timer transition at an instant the entity carries — a due date, a deadline: an entity in state from moves to state to once the time instant returns has come; false means no instant for now. kit asks again each time the entity is written, and the workflow's own loop sleeps until the earliest instant.

func (WorkflowService) Can
func (*WorkflowService) Can(e E, event string) bool

Can reports whether event may be fired on e.

func (WorkflowService) Census
func (*WorkflowService) Census(ctx context.Context) (map[S]int, error)

Census counts the entities per state; every declared state is present. The engine keeps the count; the call is drawn, as the diagram declares it, as a read of the store.

func (WorkflowService) Fire
func (*WorkflowService) Fire(ctx context.Context, key string, event string) (E, error)

Fire moves the entity with the given key along the event transition leaving its current state. It is a Conflict error when no such transition exists, and a NotFound error when the entity does not.

func (WorkflowService) Initial
func (*WorkflowService) Initial(state S) *WorkflowService[E, S]

Initial sets the state a new entity enters with WorkflowService.Start.

func (WorkflowService) On
func (*WorkflowService) On(event string, from S, to S) *WorkflowService[E, S]

On declares an event transition: WorkflowService.Fire with this event moves an entity in state from to state to. One event may leave several states, but only one arrow per (event, from).

func (WorkflowService) OnEnter
func (*WorkflowService) OnEnter(state S, fn func(context.Context, *E) error) *WorkflowService[E, S]

OnEnter runs fn when an entity enters state, before it is stored. An error cancels the transition, and so does a panic — reported as CodeWorkflowHookPanic, the entity free for the next transition. fn may change the entity, not its state nor its key (CodeWorkflowHookChange), and must not fire this workflow, which is refused (CodeWorkflowReentrant): transitions of one entity run one at a time.

func (WorkflowService) OnTransition
func (*WorkflowService) OnTransition(fn func(context.Context, ChangeEvent[E, S]) error) *WorkflowService[E, S]

OnTransition runs fn after every transition has been stored, whoever fired it — the natural place to publish it on a topic. An error or a panic is logged and shown by the Studio; the transition stands, and the next hooks still run.

func (WorkflowService) Start
func (*WorkflowService) Start(ctx context.Context, e E) (E, error)

Start enters a new entity into the workflow: it sets the initial state, runs the OnEnter hooks, and inserts the entity in the store.

func (WorkflowService) When
func (*WorkflowService) When(event string, from S, to S, guard func(E) bool) *WorkflowService[E, S]

When declares a guard transition: an entity in state from moves to state to as soon as guard holds. The guard sees the entity only: kit checks it each time the entity is written, never on a clock — a condition that depends on the time is an instant, declared with WorkflowService.At.

type WrittenEvent

WrittenEvent is what a watch is told of a write: which store, which record, and whether it was deleted — never a value. The watch reads the record itself (RecordsOf): without its secret members, and journaled.

type WrittenEvent struct {
	// Store is the store's node ID: "shop/store/reviews".
	Store   string          `json:"store"`
	// Key is the record's key in the store.
	Key     string          `json:"key"`
	// Deleted is set when the write deleted the record: there is nothing
	// left to read.
	Deleted bool            `json:"deleted,omitempty"`
	// Fields are the store's fields that carry the watch's mark, as
	// [App.Fields] lists them. Which of them the write changed, the notice
	// does not say.
	Fields  []FieldRefValue `json:"fields,omitempty"`
}

Generated from docs/api by tools/genindex.

Documentation

Overview

Package kit — who may call an operation: the principal, the rules and their checks.

Package kit — activities: what a daemon's idle stop waits for besides its connections, a notion of the product's own — sessions still open, work still queued.

Package kit — the App: the services a product mounts, served by one process.

Package kit — the static analysis a product can be given: the platform's analyzer, run in the background in dev (ADR 0147 §1).

Package kit — process profiles: what an app does with its process (ADR 0147 §5) — serve, run as a daemon, or run one CLI command — and the singleton lock.

Package kit — the architecture the graph draws: where each store keeps its data.

Package kit — authentication: the handler that says who calls, and the user it names.

Package kit — the build a graph describes: the modules and versions it was made of.

Package kit — the catalog of the generic mechanics a node is built from.

Package kit — the kit tag: the classes and words a field of personal data carries.

Package kit — the plan of a Go type's classified members, computed once per type.

Package kit — the walk of a value along its classification plan.

Package kit — the warnings for fields whose name suggests personal data left unclassified.

Package kit — CLI commands: a short command of the product that Main runs once, in the CLI profile, and whose status is the process's.

Package kit — commands: an operation that changes something, with one handler.

Package kit — the app's options and environments.

Package kit — the config command: every setting, its value and where it comes from.

Package kit — the consumer that drains a queue into its handler.

Package kit — the daemon: what a running app knows of itself beyond its nodes.

Package kit — the daemon's HTTP server as the Studio sees it: its loop, its counters, and the middleware every request goes through.

Package kit — the daemon's loops: their states, the scheduler that fires the jobs, and the goroutine labels that name them.

Package kit — databases: the SQL engines a store can be kept on.

Package kit — the start's judgement of the declared databases.

Package kit — the interfaces of databases: the engine a connector gives, and what kit asks of it.

Package kit — the migrations a database runs, and their lock.

Package kit — the placement of each store: which database keeps its data.

Package kit — a database in a running app.

Package kit — the databases as the graph shows them.

Package kit — the decoding of a request into its typed value.

Package kit — the dev tools' routes of the Studio, read-only.

Package kit is the implementation of framework/kit, the framework in which every product is its own diagram. A product imports framework/kit, whose names alias and forward to this package's: here, the types carry the role their name says — StoreService, EndpointService, AppConfigurer — and the facade keeps the names a product writes — Store, Endpoint, AppOption.

Package kit — endpoints: an HTTP route and the operation it serves.

Package kit — the errors a product returns to its callers, and their wire mapping.

Package kit — exposures: an operation an endpoint serves over HTTP.

Package kit — what an exposure takes, and what it exposes.

Package kit — the Go modules of the running binary, read from its build info.

Package kit — the graph: the product as a diagram of what it mounts.

Package kit — history: the former values of the fields that keep them.

Package kit — the history's storage: former values kept beside each record.

Package kit — reading a record's former values.

Package kit — the history as the graph and the Studio show it.

Package kit — what kit's own writes mean to the history.

Package kit — legal holds: records kept whatever their retention says.

Package kit — secondary indexes of a store.

Package kit — the Studio's read API: the graph, the events, the sources.

Package kit — what the source endpoint needs of the root it reads.

Package kit — how the source endpoint opens a file on Unix.

Package kit — how the source endpoint opens a file on Windows: the link itself, never its target.

Package kit — jobs: scheduled work run by the daemon's loop.

Package kit — the privacy journal: what kit did to personal data, and why.

Package kit — idempotency keys and their leases.

Package kit — the compile-time proof of which roles each declaration plays: the interfaces the app reaches its nodes and options through.

Package kit — listeners: inbound ports that are not HTTP, a private socket speaking a versioned contract (ADR 0148).

Package kit — the compile-time proof that a listener is a starter.

Package kit — what a listener needs of the socket it accepts on.

Package kit — the product's logger and the logs the Studio shows.

Package kit — loops: work the daemon waits for, woken by time or by events.

Package kit — mailers: a durable outbox and the transport that empties it.

Package kit — what building an SMTP transport needs of its URL.

Package kit — Main: the whole main function of a product.

Package kit — the migrate command.

Package kit — modules: a set of services a product mounts as one.

Package kit — the start's checks of the modules an app mounts.

Package kit — what a module keeps: its stores and its migrations.

Package kit — the mount of a module: its prefix and its bindings.

Package kit — nodes: what every declaration shares, and its source position.

Package kit — the interfaces of nodes: what every declaration is, and the roles some play.

Package kit — observation: the spans and events of a running product.

Package kit — operations: a typed request answered by a typed response.

Package kit — the password policy of a store's fields.

Package kit — hashing and verifying passwords under their policy.

Package kit — the warnings for endpoints that set passwords outside a policy.

Package kit — ports: an operation a service needs and does not implement.

Package kit — privacy: kit's own service for holds and the journal.

Package kit — erasure: a record's personal data removed as its retention would.

Package kit — export: a person's data as kit gives it back.

Package kit — a store's personal data as the graph shows it.

Package kit — the keys that index personal data without revealing it.

Package kit — the Studio's privacy pages: the journal, the holds, the register.

Package kit — the privacy command.

Package kit — what the privacy command prints.

Package kit — `privacy seal`: a whole store sealed now.

Package kit — the process sample: what the running process uses.

Package kit — the Studio's profiler: the live heap and the goroutines, folded onto the graph.

Package kit — queries: an operation that reads and changes nothing.

Package kit — queued commands: a command run later, from its queue.

Package kit — rate limits on an endpoint, per client.

Package kit — records: the product's data as modules and the Studio reach it.

Package kit — redaction: what a value shows once its secrets are hidden.

Package kit — the register of processing: each store's line.

Package kit — replacements: a test's substitute for an operation.

Package kit — the HTTP request and response an endpoint can reach.

Package kit — retention: how long a store keeps its personal data.

Package kit — the retention of a store in a running app.

Package kit — one pass of retention: what is due is erased or deleted.

Package kit — record revisions: a store's previous versions of each record.

Package kit — what changed between two versions, and a version written back.

Package kit — where a store's versions are kept, engine by engine.

Package kit — what the privacy rules ask of a record's versions.

Package kit — a record's version written back.

Package kit — what the Studio sees of a record's versions.

Package kit — the revisions command: a version of a record written back.

Package kit — binaries and their process roles: one executable, several Apps, and the versioned contracts between them (D22).

Package kit — schemas: the JSON Schema of an operation's types.

Package kit — scopes: the parts of a singleton's lock or of a socket's path that are only known at the start — the user, the executable, a configuration directory —, so one declaration keeps one process per user, per installed copy or per configuration.

Package kit — the current user outside Windows: the process's UID, read from the kernel. os/user would ask libc through cgo — linking the program dynamically — or read /etc/passwd, for a number the kernel gives at once.

Package kit — the current user on Windows: its SID, from os/user, which reads the process token there without cgo.

Package kit — sealing at rest: members sealed where kit keeps them.

Package kit — where the data keys are, against what they seal.

Package kit — cryptographic erasure: a data key destroyed.

Package kit — a document as it lies at rest, sealed member by member.

Package kit — messages at rest: a queue's members sealed.

Package kit — a store that seals: its records as they rest.

Package kit — a store that seals, as kit's port sees it.

Package kit — secrets: the values the product declares and the operator provides.

Package kit — the secrets command.

Package kit — where the secrets are kept, per environment.

Package kit — services: a bounded context and the building blocks it owns.

Package kit — settings: a value the environment gives a service.

Package kit — the interfaces of settings: the values a setting holds, and what kit reads of a declaration.

Package kit — frontends: static assets the product serves.

Package kit — stores: a typed, keyed collection of entities.

Package kit — the engines a store runs on: memory, files or a database.

Package kit — stores on SQL: the SDK's document store over a database.

Package kit — kit's own migrations on a database.

Package kit — telemetry: the numbers a product reports, exported on a private socket when the deployment asks for them (ADR 0149).

Package kit — topics and subscriptions: asynchronous messages of one type.

Package kit — transactions: kit.Transact and its levels.

Package kit — a transaction on a database, the database's own.

Package kit — the data's writer turn, where there are no transactions.

Package kit — a transaction writes one database: the dev warning.

Package kit — watches: how a module hears the writes of a product's marked fields.

Package kit — a watch in a running app: its queue and its consumer.

Package kit — the sentences kit says, in every language it speaks.

Package kit — workflows: a state machine over the entities of one store.

Package kit — the ports the workflow engine reaches a store through.

Index

Constants

View Source 
const (
	CodeStoreDecode  errs.Code = 0x00_04_02_01 // 0.4.2.1 — a stored entity no longer decodes into its type
	CodeStoreEncode  errs.Code = 0x00_04_02_02 // 0.4.2.2 — an entity does not encode to JSON
	CodeStorePersist errs.Code = 0x00_04_02_03 // 0.4.2.3 — the store file could not be written
	CodeStoreLoad    errs.Code = 0x00_04_02_04 // 0.4.2.4 — the store file could not be read at start
	CodeStoreIndex   errs.Code = 0x00_04_02_05 // 0.4.2.5 — the stored entities break a unique index, or a key function panicked
	CodeTopicEncode  errs.Code = 0x00_04_02_06 // 0.4.2.6 — a message does not encode to JSON
	CodeTopicPublish errs.Code = 0x00_04_02_07 // 0.4.2.7 — a subscription's queue refused a message
	CodeQueueOpen    errs.Code = 0x00_04_02_08 // 0.4.2.8 — a subscription's queue could not be opened
	CodeUndecodable  errs.Code = 0x00_04_02_09 // 0.4.2.9 — a delivered message does not decode
	CodeHandlerPanic errs.Code = 0x00_04_02_0A // 0.4.2.10 — a subscription handler panicked
	CodeNotMounted   errs.Code = 0x00_04_02_0B // 0.4.2.11 — a subscription's topic is not mounted in the app
	CodeWorkflowLoad errs.Code = 0x00_04_02_0C // 0.4.2.12 — a workflow's bookkeeping could not be read at start

	// A workflow hook panicked: an OnEnter hook fails its transition with it,
	// an OnTransition hook is reported and the transition stands.
	CodeWorkflowHookPanic errs.Code = 0x00_04_02_0D // 0.4.2.13

	// An OnEnter hook changed the state its entity was entering, or the
	// entity's key: the transition is refused.
	CodeWorkflowHookChange errs.Code = 0x00_04_02_0E // 0.4.2.14

	// An OnEnter hook fired its own workflow: refused, where it would wait
	// for itself.
	CodeWorkflowReentrant errs.Code = 0x00_04_02_0F // 0.4.2.15
	CodeAppConfig         errs.Code = 0x00_04_02_10 // 0.4.2.16 — the app's configuration cannot be applied
	CodeAppRunning        errs.Code = 0x00_04_02_11 // 0.4.2.17 — the app, or one of its services, is already running
	CodeAppListen         errs.Code = 0x00_04_02_12 // 0.4.2.18 — the app could not listen on its address

	// Mailers.
	CodeMailConfig errs.Code = 0x00_04_02_13 // 0.4.2.19 — KIT_SMTP_URL cannot be used
	CodeMailEncode errs.Code = 0x00_04_02_14 // 0.4.2.20 — a mail does not encode for the outbox
	CodeMailQueue  errs.Code = 0x00_04_02_15 // 0.4.2.21 — the outbox could not be opened, or refused a mail

	// Deprecated: kit no longer returns it. The outbox is the SDK's mail
	// spool, which dead-letters a record that does not decode itself
	// (MessageUndecodable, in pkg/v1/app/mail/spool).
	CodeMailUndecodable errs.Code = 0x00_04_02_16 // 0.4.2.22
	CodeMailPanic       errs.Code = 0x00_04_02_17 // 0.4.2.23 — a delivery attempt panicked

	// Loops.
	CodeLoopPanic      errs.Code = 0x00_04_02_18 // 0.4.2.24 — a loop's function panicked
	CodeLoopNotMounted errs.Code = 0x00_04_02_19 // 0.4.2.25 — a loop wakes on a topic whose service is not mounted in the app
	CodeLoopStart      errs.Code = 0x00_04_02_1A // 0.4.2.26 — a hand-written loop's supervisor refused to start

	// Secrets.
	CodeSecretStore   errs.Code = 0x00_04_02_1B // 0.4.2.27 — the environment's secret store cannot be used: KIT_SECRETS, KIT_SECRETS_KEY
	CodeSecretMissing errs.Code = 0x00_04_02_1C // 0.4.2.28 — a declared secret is found nowhere
	CodeSecretRead    errs.Code = 0x00_04_02_1D // 0.4.2.29 — a secret's store refused to read it
	CodeSecretRotate  errs.Code = 0x00_04_02_1E // 0.4.2.30 — a generated secret could not be made or rotated

	// Databases, ADR 0004.
	CodeDatabaseOpen        errs.Code = 0x00_04_02_1F // 0.4.2.31 — a database's engine could not open its pool
	CodeDatabaseMigrate     errs.Code = 0x00_04_02_20 // 0.4.2.32 — a database's migrations did not apply, or wait for `migrate up`
	CodeDatabaseUnavailable errs.Code = 0x00_04_02_21 // 0.4.2.33 — a database did not answer
	CodeDatabaseConfig      errs.Code = 0x00_04_02_22 // 0.4.2.34 — a database's URL or tuning cannot be used
	CodeDatabaseVersion     errs.Code = 0x00_04_02_4C // 0.4.2.76 — a database's server is below kit's floor: MySQL 8.0.1, MariaDB 10.6

	// A transaction wrote a store another database keeps than the one it
	// belongs to — the data directory counting as one: refused, Invalid.
	CodeTransactionSpan errs.Code = 0x00_04_02_42 // 0.4.2.66

	// Privacy (ADR 0006).
	CodePrivacyKey     errs.Code = 0x00_04_02_23 // 0.4.2.35 — kit's index key cannot be read, made or derived
	CodePrivacyErase   errs.Code = 0x00_04_02_24 // 0.4.2.36 — an erasure failed: the store's Anonymise function panicked
	CodePrivacyJournal errs.Code = 0x00_04_02_25 // 0.4.2.37 — the privacy journal cannot be read or written
	CodePrivacyData    errs.Code = 0x00_04_02_26 // 0.4.2.38 — the privacy command cannot open the data: the product runs, or keeps it in memory

	// History (ADR 0007).
	CodeHistoryLoad  errs.Code = 0x00_04_02_27 // 0.4.2.39 — a store's history cannot be opened at start
	CodeHistoryWrite errs.Code = 0x00_04_02_28 // 0.4.2.40 — a store's history cannot be written: the record's write is refused with it
	CodeHistoryRead  errs.Code = 0x00_04_02_29 // 0.4.2.41 — a store's history cannot be read
	CodePasswordHash errs.Code = 0x00_04_02_2A // 0.4.2.42 — a password cannot be hashed, or a stored hash cannot be read

	// Commands and queries.
	CodeCommandReentrant errs.Code = 0x00_04_02_2B // 0.4.2.43 — a handler dispatched its own command with its own key: refused, never a deadlock
	CodeCommandKey       errs.Code = 0x00_04_02_2C // 0.4.2.44 — a command's key could not be held
	CodeCommandQueue     errs.Code = 0x00_04_02_2D // 0.4.2.45 — a queued command's queue could not be opened, or refused a dispatch
	CodeCommandEncode    errs.Code = 0x00_04_02_2E // 0.4.2.46 — a queued command's input does not encode for its queue

	// Watches (ADR 0008).
	CodeWatchQueue  errs.Code = 0x00_04_02_2F // 0.4.2.47 — a watch's queue could not be opened, or refused a notice: lost when the write stands, the transaction's failure when it joined it
	CodeRecordsKeys errs.Code = 0x00_04_02_4D // 0.4.2.77 — Records.Keys asked by a caller none of whose module's watches the store feeds: refused, Forbidden

	// Sealing at rest (ADR 0006, step 3).
	CodeSealKey    errs.Code = 0x00_04_02_3D // 0.4.2.61 — kit's data keys cannot be reached: data-key, or kit's own store of data keys
	CodeSealWrite  errs.Code = 0x00_04_02_3E // 0.4.2.62 — a member could not be sealed: the write is refused, nothing changed
	CodeSealOpen   errs.Code = 0x00_04_02_3F // 0.4.2.63 — a sealed member does not open: altered, moved, or its data key does not unwrap
	CodeSealRewrap errs.Code = 0x00_04_02_40 // 0.4.2.64 — data-key's rotation could not re-wrap every data key: the old version is kept
	CodeSealShred  errs.Code = 0x00_04_02_41 // 0.4.2.65 — an erasure could not destroy a data key: the erasure's rewrite stands

	// Revisions (ADR 0007 §3).
	CodeRevisionRead   errs.Code = 0x00_04_02_43 // 0.4.2.67 — a record's versions cannot be read, or two of them compared
	CodeRevisionWrite  errs.Code = 0x00_04_02_44 // 0.4.2.68 — a record's versions cannot be rewritten: an erasure's, a hold's, a rollback's
	CodeRevisionDecode errs.Code = 0x00_04_02_45 // 0.4.2.69 — a version no longer decodes into the store's type: Revisions, Revision and Restore refuse it

	// The framework's own signals and refusals, typed since the move into the
	// SDK (rule 2: no fmt.Errorf, no errors.New in production code).
	CodeJobOverlapped  errs.Code = 0x00_04_02_31 // 0.4.2.49 — a scheduled job's run was skipped: the previous one is still going
	CodeHistoryMoved   errs.Code = 0x00_04_02_32 // 0.4.2.50 — an undo ended: another write changed the history since
	CodeNotSource      errs.Code = 0x00_04_02_33 // 0.4.2.51 — the source endpoint's name holds no regular file
	CodePasswordMoved  errs.Code = 0x00_04_02_34 // 0.4.2.52 — a password write ended: another write changed the hash since
	CodeNothingToErase errs.Code = 0x00_04_02_35 // 0.4.2.53 — an erasure's update found nothing to erase
	CodeKeyRekeyed     errs.Code = 0x00_04_02_36 // 0.4.2.54 — an erasure's update would change a key that depends on personal data
	CodeMigrateRefused errs.Code = 0x00_04_02_37 // 0.4.2.55 — the migrate command cannot do what it was asked
	CodeCatalogue      errs.Code = 0x00_04_02_38 // 0.4.2.56 — the framework's own message catalogues disagree
	CodeRetentionPanic errs.Code = 0x00_04_02_39 // 0.4.2.57 — a store's retention function panicked

	// The signals kit ends one of its own steps with and catches itself — a
	// caller never receives one —, typed when the SDK made rule 2 a gate
	// (make guard), where they had been stdlib errors.
	CodeSealErased         errs.Code = 0x00_04_02_46 // 0.4.2.70 — a sealed value's data key is destroyed: kit reads the value as its zero value
	CodeSealKeyMoved       errs.Code = 0x00_04_02_47 // 0.4.2.71 — a data key's replacement ended: another write changed the wrapped key since
	CodeResealInPlace      errs.Code = 0x00_04_02_48 // 0.4.2.72 — a write that changed nothing ended, for the record to be sealed again in place: no version
	CodeResealMoved        errs.Code = 0x00_04_02_49 // 0.4.2.73 — a reseal in place ended: another write changed the record since
	CodeWorkflowNotInPlace errs.Code = 0x00_04_02_4A // 0.4.2.74 — a transition's write in place ended: it changes more than the state, so it makes a version
	CodeTransactionPanic   errs.Code = 0x00_04_02_4B // 0.4.2.75 — a transaction's function, or a function held until its commit, panicked: the panic continues
)

The framework's own failures carry SDK error codes in 0.4.2.* — layer 4 is the framework's, PP 2 this package (ADR 0147 §3) — so a product keeps the whole application range 0x40–0x7F for its own codes. Match them with errs.HasCode. Their Public text is the only part that may reach a caller; none of them is a 4xx, so a caller only ever reads "internal error".

View Source 
const (
	// EnvDev serves the Studio, analyzes the source and binds loopback. Only
	// `kit dev` or an explicit KIT_ENV=dev turns it on.
	EnvDev = "dev"
	// EnvProduction is the default: no Studio, no source, no analysis.
	EnvProduction = "production"
)

The environments.

View Source 
const (
	WireInvalid     = "invalid_argument"
	WireNotFound    = "not_found"
	WireConflict    = "conflict"
	WireUnauth      = "unauthenticated"
	WireForbidden   = "permission_denied"
	WireTooLarge    = "too_large"
	WireUnsupported = "unsupported_media_type"
	WireRateLimited = "rate_limited"
	WireUnavailable = "unavailable"
	WireTimeout     = "deadline_exceeded"
	WireCanceled    = "canceled"
	WireInternal    = "internal"
)

The wire codes a caller branches on: an Error's Code, snake_case, kept byte-for-byte from the platform's kit (ADR 0147 §6). They are named Wire*, not Code*, because Code* names a dotted-quad errs.Code in the SDK and the registry audit holds every Code* constant to that.

View Source 
const CodeCLIFailed errs.Code = 0x00_04_02_3B // 0.4.2.59 — a CLI command exited with a non-zero status

CodeCLIFailed marks the span of a CLI command that exited non-zero.

View Source 
const CodeProfileRead errs.Code = 0x00_04_02_30 // 0.4.2.48

CodeProfileRead reports a profile of the process that could not be written or read back. It is in the framework's 0.4.2.* range.

View Source 
const CodeScopeUnknown errs.Code = 0x00_04_02_3C // 0.4.2.60 — a scope's value could not be read

CodeScopeUnknown reports a scope whose value could not be read at the start: no current user, no executable path, no configuration directory.

View Source 
const CodeSingletonHeld errs.Code = 0x00_04_02_3A // 0.4.2.58 — another process of the app holds its singleton lock

CodeSingletonHeld reports a start refused because another process of the app holds its singleton lock.

View Source 
const DefaultMaxBody int64 = 1 << 20

DefaultMaxBody is the largest request body an endpoint reads, unless the endpoint says otherwise with MaxBody.

Variables

View Source 
var (
	// PerUID is the current user: one process per user of the machine (its
	// UID on Unix, its SID on Windows).
	PerUID = ScopeValue{/* contains filtered or unexported fields */}

	// PerExecutable is the running executable's path, links resolved: one
	// process per installed copy of the binary.
	PerExecutable = ScopeValue{/* contains filtered or unexported fields */}

	// PerConfigDir is the user's configuration directory (os.UserConfigDir):
	// one process per configuration home.
	PerConfigDir = ScopeValue{/* contains filtered or unexported fields */}
)
View Source 
var Privacy = &Service{name: privacyService, doc: privacyDoc, ids: map[string]bool{}}

Privacy is kit's own service: the data keys, the legal holds and the privacy journal of an app that keeps personal data or seals what it keeps. kit mounts a copy of it — named kit.privacy, a name no service of a product can take — in every app whose stores keep personal data or declare a retention, or that keeps sealed values at rest, before the product's services. Its stores stay in the data directory unless the product places them (ADR 0004): kit.Keeps(kit.Privacy). On a SQLite database its data keys stay in the data directory all the same — a key is written apart from every transaction, and the file's one writer may be held by the transaction of the write that needs it —; its holds and its journal go there. A product never mounts it itself.

Functions

func After 

func After(ctx context.Context, d time.Duration) <-chan time.Time

After is time.After on the app's clock.

func AuthData 

func AuthData[D any](ctx context.Context) (D, bool)

AuthData returns what the auth handler said about the caller, and whether there is a caller whose data has type D.

func Bind 

func Bind[Req, Resp any](port *PortService[Req, Resp], op Operation[Req, Resp]) interface {
	AppConfigurer
	MountConfigurer
}

Bind makes the app's port call op, whatever implements the port and whatever its fallback: an endpoint — or, with ADR 0005, a command or a query — of the port's types. A binding is code, the same in every environment; a binding to a port, or to a service the app does not mount, is refused when the app starts. Given twice for one port, the last wins. 

app := kit.NewApp("vigie", desk.Service, posts.Service).With(kit.Bind(desk.Enforcer, posts.EnforceAPI))

It is an option of Mount too, under the same name: there it binds a port of the module mounted, and another is refused. 

app := kit.NewApp("shop", posts.Service).With(kit.Mount(moderation.Module, kit.Bind(moderation.Enforcer, posts.EnforceAPI)))

func Catalog 

func Catalog() []model.Mechanic

Catalog lists the generic mechanics kit offers: the building blocks a node composes rather than implements, each one backed by an SDK package. It is part of every graph, so the Studio — and an AI agent reading the graph — knows what can be added to a product and the exact code that adds it.

func ClearCookie 

func ClearCookie(ctx context.Context, name string)

ClearCookie tells the browser to forget the cookie called name.

func ClientIP 

func ClientIP(ctx context.Context) string

ClientIP returns the address of the client of the request ctx serves: the connection's peer, or — only when KIT_TRUST_PROXY=on — the last address of X-Forwarded-For, the one the trusted proxy appended. It is "" outside an HTTP request.

func EnableServer 

func EnableServer()

EnableServer makes an app in the server profile serve HTTP. framework/kit/server calls it as it is imported; a product never does.

func EnableStudio 

func EnableStudio()

EnableStudio makes a serving app in dev mount the Studio's API. framework/kit/studio calls it as it is imported; a product never does.

func HoldSubject 

func HoldSubject(ctx context.Context, reason string, ids ...string) error

HoldSubject places a legal hold on every record whose subject is one of ids, in every store of the app: an authority's request about a person. It holds the records they have now; a record written later is not held. reason is kept as Store.Hold keeps it.

func InMemory 

func InMemory() interface {
	StoreConfigurer
	AppConfigurer
}

InMemory keeps data in memory. On an app, it overrides the data directory for every store and queue — KIT_DATA_DIR, and a DataDir given before it: what a test wants. On a store, it keeps that store in memory even when the app has a data directory.

func Log 

func Log(ctx context.Context) logger.Logger

Log returns the app's logger, for the node ctx runs inside. In dev, every record it writes inside a span is also kept beside that span, so the Studio shows a request's logs with its trace.

func Migrations 

func Migrations(m ...sql.Migration) interface {
	DatabaseConfigurer
	ModuleConfigurer
}

Migrations are migrations, values of the SDK's sql.Migration, run when the database starts (<name>-migrate: start) or by `<product> migrate up`, kit's own first, each set under its own version table — and so its own lock. On MySQL a DDL statement commits by itself: write one per migration.

Given to Database, they are the product's, under schema_migrations. Given to NewModule, they are the module's (ADR 0008), for the data it keeps outside kit's stores: run on the database that keeps the module, under <module>_migrations.

func NewID 

func NewID(prefix string) string

NewID returns a new identifier with the given prefix: a TypeID, time ordered, like "todo_01k5zq7m3xe8tvbfg0s7zr4w6c". The prefix must be one to sixty-three lower-case letters, with '_' only between two letters; any other prefix is a programming error and panics.

func NewTicker 

func NewTicker(ctx context.Context, d time.Duration) clock.Ticker

NewTicker is a ticker of period d on the app's clock, for a loop written by hand (Service.Go): a test's manual clock drives it like every timer kit runs itself, where a time.Ticker would tick on the wall clock whatever the test does. It panics on a non-positive d, as time.NewTicker does.

func Now 

func Now(ctx context.Context) time.Time

Now returns the app's time: the system clock, or the clock a test gave with Clock. Product code that compares with a deadline reads it rather than time.Now, so that a test's manual clock reaches it.

func RegisterConfigFormat 

func RegisterConfigFormat(ext, format string)

RegisterConfigFormat lets configuration files of extension ext be read with the SDK codec format. framework/kit/config/yaml and config/toml call it as they are imported; a product never does.

func ScopeKey 

func ScopeKey(scopes ...ScopeValue) (string, error)

ScopeKey is the name the scopes give in this process: 16 hex digits of the SHA-256 of their values. A client computes the key the daemon computed from the same declaration, and so finds its lock or its socket.

func SetCookie 

func SetCookie(ctx context.Context, c *http.Cookie)

SetCookie adds a Set-Cookie header to the HTTP response of the endpoint ctx serves. kit fills what a cookie left zero with safe defaults — Path "/", HttpOnly, SameSite Lax, and Secure outside dev — so a session cookie is hardened unless the code says otherwise. In an in-process EndpointService.Call there is no response: the cookie is dropped.

HttpOnly is always set, and Secure always outside dev (and in dev for SameSite=None, which browsers require): a boolean has no "unset" a default could fill, and kit chooses the hardened reading. A cookie set more than once in one response keeps its last value, and cookies set before an error are sent with the error — clearing a stale session on a 401 works.

func SocketPathFor 

func SocketPathFor(product, service, name string, scopes ...ScopeValue) (string, error)

SocketPathFor is the socket of the listener name of service in product — the binary's name for a role of one, else the app's —, placed by default and named after scopes (SocketPer): the one rule, for a client of another process role that does not import the daemon's declarations (D22) — it names the three words and the scopes its contract states. The service is its qualified name for a module's.

func Stop 

func Stop(ctx context.Context) bool

Stop asks the app ctx runs in to end its run: Run returns as it does on a signal, its stop draining every component — a daemon told "stop" by its client, on its listener, ends itself so. It returns at once, before the stop; it reports false when ctx runs in no app — a handler's, a loop's, a command's context does — or the app does not run.

func Transact 

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

Transact runs fn in one transaction and returns fn's error: nil commits what fn wrote, an error undoes it — a panic too, which then continues. 

err := kit.Transact(ctx, func(ctx context.Context) error {
	if _, err := Cases.Update(ctx, id, closeCase); err != nil {
		return err // what this function wrote is undone
	}
	if err := Decisions.Insert(ctx, d); err != nil {
		return err
	}
	return Changes.Publish(ctx, Closed{ID: id}) // held: queued at the commit
})

A transaction belongs to one database: the one its first store call reaches — at its first call on a database, at its first write on the data directory, which counts as one, memory with it. Inside it, a store of another database is read as usual; writing one is refused (Invalid, CodeTransactionSpan). A Transact inside another is a savepoint: its failure undoes its own writes, and the outer transaction goes on if its caller handles the error.

What leaves the process waits for the outermost commit: a topic's publish, a queued command's dispatch, a mail — whose outbox ID Mailer.Send returns at once —, a watch's notice, the store's write hooks that wake workflows and loops, a workflow's OnTransition hooks. Each is checked when it is made, so a caller's mistake returns to the caller; a rollback drops them, and a savepoint's rollback its own. A publish, a dispatch, a mail or a notice whose queue lives on the transaction's database — the one that keeps the service of its subscription, command, mailer or watch, by a store's rules — is written in the transaction, just before it commits, a mail sealed under kit's data-key: a queue that refuses it fails the transaction, every write undone, and Transact returns the refusal. Every other one leaves after the commit: one a queue refuses then is logged and reported, and the commit stands; a process that dies between the commit and the release loses what was held.

On a database the transaction is the database's own, at its default isolation. On the data directory and in memory kit keeps its own: it takes the data's writer turn — one transaction at a time; a write outside any waits for it, and such writes share the turn among themselves —, its writes land at once, and an error writes each entity's previous value back, newest first. It is atomic against an error, not against a crash, and a reader may see a write before its commit. A store kept in memory by InMemory — a cache — is in no transaction: its writes land and stay.

A command's handler runs in one already (NoTransaction opts out), and so does a workflow's transition.

func UserAgent 

func UserAgent(ctx context.Context) string

UserAgent returns the User-Agent of the request ctx serves, clipped.

func WithUser 

func WithUser[D any](ctx context.Context, uid UID, data D) context.Context

WithUser returns ctx acting as the given user, with data: what a job, a loop or a test uses to call an Auth endpoint in-process on someone's behalf.

Types

type ActivityHandler 

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

ActivityHandler is a declared activity of a service: a function that says whether the product is busy. A daemon's IdleStop waits until every activity of its mounted services says false AND no connection is open on its listeners.

type AnalyzeFunc 

type AnalyzeFunc func(ctx context.Context, dir string, modules []string) (*model.Graph, error)

AnalyzeFunc reads the product's source — the Go module rooted at dir, and the packages that declare the modules it mounts — into a graph the runtime merges into its own: the edges found in handler bodies, each function's steps. The framework links no analyzer (ADR 0147 §1): the platform's kit tool gives one, in dev, through Analyzer.

type App 

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

App is the whole product: the services it mounts, served by one process. The same services can be mounted by several apps — one binary per service, or all of them in one — and each app draws exactly what it runs.

func NewApp 

func NewApp(name string, services ...*Service) *App

NewApp declares the product named name, made of services. A module's services come with the module: App.With mounts it.

func (*App) Fields 

func (a *App) Fields(m Mark) []FieldRefValue

Fields lists the fields of the app's stores that carry the mark, store by store in the order the app mounts them, each in its entity's order. Personal lists special fields too: they are personal data.

func (*App) Graph 

func (a *App) Graph() *model.Graph

Graph returns the product as a diagram: every node the app mounts with the position of its declaration, the edges that exist by construction, the edges observed at runtime with their counters, and — in dev, once the static analysis has run — the edges found in the handlers' code with their call sites. It is what the Studio draws and what `<app> graph` prints.

func (*App) Handler 

func (a *App) Handler() http.Handler

Handler returns the app's HTTP handler, once started: what httptest wraps.

func (*App) Main 

func (a *App) Main(ctx context.Context, args []string) int

Main is the whole main function of a product: 

func main() { os.Exit(App.Main(context.Background(), os.Args[1:])) }

It understands eight commands, so every kit binary can describe itself, be probed, say its configuration, manage its secrets, migrate its databases and answer for the personal data it keeps without a shell or another tool in its image: 

serve        run the product (the default)
graph        print the product graph: -format json|mermaid
healthcheck  exit 0 when the product running on KIT_ADDR is ready
config       every setting: its value, never a secret's, and its origin
secrets      list the secrets, set one from standard input, rotate one
migrate      the databases' migrations: status, up, down SET VERSION
privacy      the register of processing, a person's export and erasure,
             the legal holds, the privacy journal, the retention
revisions    a record's version restored

A product's CLI command runs when the first argument names it. A command declared with DefaultCommand runs when the first argument names no command at all — with every argument —, and when there is none, in serve's place: Main then never answers a usage error.

It returns the process exit status rather than exiting, so that deferred work runs and a test can call it.

func (*App) Name 

func (a *App) Name() string

Name returns the product name.

func (*App) Records 

func (a *App) Records(store string) (RecordsService, error)

Records returns the untyped port to the records of the store whose node ID is store: what kit's export and erasure run on, and what a module reads and erases through. A store the app does not mount is a NotFound error.

func (*App) Run 

func (a *App) Run(ctx context.Context) error

Run starts the product, serves until ctx ends or the process receives SIGINT or SIGTERM, then drains it.

Goroutine lifecycle: one goroutine turns a signal into the run's cancellation; it ends when a signal arrives or when the run returns, which cancels the context it also watches.

func (*App) Start 

func (a *App) Start(ctx context.Context) error

Start brings the product up: it checks every declaration, opens the data directory, loads the stores, starts the consumers, the scheduler and the HTTP listener — in that order, through the SDK lifecycle, so a failure unwinds what already started. It returns once the product serves.

func (*App) Stop 

func (a *App) Stop(ctx context.Context) error

Stop drains the product: readiness turns false, then the components stop in reverse order — the HTTP listener finishes its requests before the stores close.

func (*App) URL 

func (a *App) URL() string

URL returns the base URL the app listens on, once started.

func (*App) With 

func (a *App) With(opts ...AppConfigurer) *App

With returns a new app: the same product, with the options of a and then opts — a module among them is mounted. a itself is left as it was, so the options a test gives the product's App — a kit.Set, a kit.Replace — end with that test.

type AppConfigurer 

type AppConfigurer interface {
	// contains filtered or unexported methods
}

AppConfigurer configures an app. Options win over the environment.

func Analyze 

func Analyze(on bool) AppConfigurer

Analyze switches the in-process static analysis on or off in dev.

func Analyzer 

func Analyzer(fn AnalyzeFunc) AppConfigurer

Analyzer runs fn in the background once the product serves, in dev and when KIT_ANALYZE allows it. Without one, the graph is the runtime's alone.

func Clock 

func Clock(c clock.Timed) AppConfigurer

Clock makes the app read and wait on c instead of the system clock: a test drives timer transitions and jobs with a clock.ManualClock.

func ConfigFiles 

func ConfigFiles(fsys fs.FS) AppConfigurer

ConfigFiles gives kit the product's configuration files: config/config.<ext>, which every environment reads, and config/<env>.<ext>, the environment's own — <env> being KIT_ENV as written, dev when kit dev runs the product — in JSON, YAML or TOML (json, yaml or yml, toml). A file maps the names of the settings to their values; it never holds a secret, and a key no service declares stops the start. The files belong in the binary: 

//go:embed config
var configFiles embed.FS

app := kit.NewApp("todo", ...).With(kit.ConfigFiles(configFiles))

func DataDir 

func DataDir(dir string) AppConfigurer

DataDir sets where stores and queues persist, instead of KIT_DATA_DIR. Given to an app after InMemory, it wins: the last of the two says where the data is — so a test helper that runs the product in memory runs it on disk with the one option its test gives (kittest.NewDisk).

func Database 

func Database(name string, engine Engine, opts ...DatabaseConfigurer) AppConfigurer

Database declares a database the product keeps its stores in, named name, on engine — an engine module's, which the product's main imports: 

import (
	"github.com/kitsunium/sdk/framework/connectors/postgres"
	"github.com/kitsunium/sdk/framework/connectors/sqlite"
)

var App = kit.NewApp("vigie", intake.Service, desk.Service, audit.Service).With(
	// Keeps every store no other database keeps.
	kit.Database("database", postgres.Engine()),
	// The audit trail apart.
	kit.Database("archive", sqlite.Engine(), kit.Keeps(audit.Service)),
)

name is 1 to 49 lower-case letters, digits and dashes, not starting with "kit-", unique among the app's databases. It names the database's URL, the secret <name>-url — the variable <APP>_<NAME>_URL, or <APP>_<NAME>_URL_FILE naming a file that holds it, then the environment's secret store —, and its settings: <name>-max-open (10), <name>-max-idle (2), <name>-max-lifetime (30m), <name>-max-idle-time (0: none), <name>-timeout (5s), <name>-check-timeout (5s) and <name>-migrate (start, or manual). Outside dev the URL is required and writes its TLS mode; in dev a database without one leaves its stores in the data directory, and a SQLite database without one is the file <data>/<name>.sqlite. InMemory on the app opens none.

func DesignDigest 

func DesignDigest(digest string) AppConfigurer

DesignDigest records the digest of the design the product's code was generated from — what the generated wiring passes —, so the telemetry handshake can say it and a tool attached to the product can tell a process built from another design.

func Env 

func Env(env string) AppConfigurer

Env selects the environment, instead of KIT_ENV.

func IdleStop 

func IdleStop(d time.Duration) AppConfigurer

IdleStop makes a daemon stop itself once, for d, no connection was open on any of its listeners and no activity of its services (Service.Activity) said it was busy: a daemon launched on demand by its clients ends when they stop coming. It is refused outside the daemon profile.

func Listen 

func Listen(addr string) AppConfigurer

Listen sets the listening address, instead of KIT_ADDR or PORT. ":0" picks a free port; App.URL tells which.

func Logs 

func Logs(w io.Writer) AppConfigurer

Logs sends the app's logs to w instead of standard error.

func Mount 

func Mount(m *Module, opts ...MountConfigurer) AppConfigurer

Mount mounts module m with options: Prefix serves its routes elsewhere than "/<module>/", Bind chooses what one of its ports calls. 

app := kit.NewApp("vigie", identity.Service).
	With(kit.Mount(moderation.Module, kit.Prefix("/"), kit.Bind(moderation.Enforcer, posts.EnforceAPI)))

A module is mounted once per app: mounted again, its prefix is the last one given, and its bindings join the others, the last of a port winning.

func Profile 

func Profile(p string) AppConfigurer

Profile selects the app's process profile: model.ProfileServer (the default), model.ProfileDaemon or model.ProfileCLI.

func Replace 

func Replace[Req, Resp any](op Operation[Req, Resp], fn func(context.Context, Req) (Resp, error)) AppConfigurer

Replace runs fn in place of op's code, in the app it is given to: an endpoint's handler — or, with ADR 0005, a command's or a query's — or what a port calls. It replaces the code, not the mechanics: authentication, decoding, validation and the policies still run, and a replaced port needs no binding, so a module's tests run without a host. fn takes op's request and returns its response, or it does not compile.

A replaced run's span carries mock: replace, and runtime.mocks lists the replacement. It is for tests: the start refuses it in a program go test did not build — neither a production binary nor kit dev can carry one. Given twice for one operation, the last wins. 

app := App.With(kit.Replace(apps.AppAPI, func(ctx context.Context, in apps.IDInput) (apps.Profile, error) {
	return apps.Profile{ID: in.AppID}, nil
}))

func SecretStore 

func SecretStore(store secret.Store) AppConfigurer

SecretStore keeps the secrets in store instead of the environment's: a test gives a store holding what its provided secrets hold. The environment's variables are still read first.

func Set 

func Set(name string, value any) AppConfigurer

Set gives the setting name a value in code, over the environment and the files: a value of the setting's type, or its text as a variable would hold it. It is for tests.

func Singleton 

func Singleton(scope string) AppConfigurer

Singleton keeps one process of the app alive per scope on this machine: the start takes an exclusive file lock named after scope in the app's runtime directory (pkg/v1/app/lock: flock, LockFileEx) and holds it until the process ends. A second process refuses to start with CodeSingletonHeld — for a daemon's client, the sign to talk to the one that runs. The kernel drops the lock with a dead process.

func SingletonPer 

func SingletonPer(scopes ...ScopeValue) AppConfigurer

SingletonPer keeps one process of the app alive per value of scopes on this machine — per user, per installed executable, per configuration directory (PerUID, PerExecutable, PerConfigDir, PerEnv) —: the lock is named after the scopes' key (ScopeKey), computed at the start, and held as Singleton's is. A client that must find the process computes the same key from the same scopes.

func Studio 

func Studio(on bool) AppConfigurer

Studio switches the Studio on or off in dev. It is always off in production.

func Telemetry 

func Telemetry(path string, gids ...int) AppConfigurer

Telemetry exports the app's telemetry on the private socket at path — absolute, and short enough for a Unix socket (pkg/v1/proc/ipc) — admitting the groups gids besides the product's own account. It wins over KIT_TELEMETRY.

type AttrsProvider 

type AttrsProvider interface {
	Attrs() []authz.Attr
}

AttrsProvider is what the app's auth data says about the caller to the SDK's authz: the attributes Command.Allow and Query.Allow hand a policy — the caller's roles, its groups. Auth data that does not implement it gives none, and every Allow refuses: the start warns of it. 

type Me struct{ Roles []string }

func (m Me) Attrs() []authz.Attr { return []authz.Attr{authz.AttrStrings("roles", m.Roles...)} }

kit calls the caller a principal: in kit, a subject is the person personal data is about (ADR 0006).

type AuthenticatorHandler 

type AuthenticatorHandler[P, D any] struct {
	// contains filtered or unexported fields
}

AuthenticatorHandler is the app's authentication handler: it turns the credentials of a request — a session cookie, a bearer token — into a user, in front of every endpoint declared with Auth or AuthOptional. An app has at most one.

P is the credentials: a struct whose fields are tagged cookie:"…" or header:"…", decoded like an endpoint's request. D is what the handler says about the user; endpoints read it with AuthData.

func (*AuthenticatorHandler) ID 

func (n *AuthenticatorHandler) ID() string

ID returns the node's identifier in the product graph: "<service>/<kind>/<name>".

type Binary 

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

Binary is one executable the product ships, made of process roles: a status line and its daemon are two roles of one binary, "statusline" and "statusline daemon". Each role is an App — its own services, its own profile — and two roles talk only through a declared, versioned contract (D22): a listener one serves and the other dials, never each other's code. 

var Binary = kit.NewBinary("statusline", "The status line of a Claude session.").
	Role("render", RenderApp).                // statusline ...
	Role("daemon", DaemonApp, "daemon").      // statusline daemon ...
	Talks("render", "daemon", "render/v1")

func main() { os.Exit(Binary.Main(context.Background(), os.Args[1:])) }

The package that declares a binary and its roles is wiring, generated from the design (D22).

func NewBinary 

func NewBinary(name, doc string) *Binary

NewBinary declares the binary named name.

func (*Binary) Main 

func (b *Binary) Main(ctx context.Context, args []string) int

Main runs the role the arguments select — the one whose args are the longest prefix of them, else the default role — with the rest of the arguments, through its App's Main. It returns the process exit status.

func (*Binary) Role 

func (b *Binary) Role(name string, app *App, args ...string) *Binary

Role adds a process role named name, run by app, selected when the process's first arguments are args; the role without args is the default. It returns b, so roles chain.

func (*Binary) Talks 

func (b *Binary) Talks(from, to, contractName string) *Binary

Talks declares that role from talks to role to through contract — "<name>/v<major>". It is the only edge two roles may have.

type CLI 

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

CLI is a short command-line command of the product: it runs once, in the CLI profile, and exits with its status. Main runs it when the process's first argument is its name.

func (*CLI) ID 

func (n *CLI) ID() string

ID returns the node's identifier in the product graph: "<service>/<kind>/<name>".

type CLIFunc 

type CLIFunc func(ctx context.Context, args []string, std StdioValue) int

CLIFunc is a CLI command's body: its arguments after its name, and the streams; it returns the process exit status (0 success, 64 usage, 70 software — the sysexits a shell script branches on).

type ChangeEvent 

type ChangeEvent[E any, S comparable] struct {
	// Key is the entity's key in the store.
	Key string
	// Entity is the entity, as stored after the transition.
	Entity E
	// Event is the transition's name; "create" for [WorkflowService.Start].
	Event string
	// From is the state left; the zero S on creation.
	From S
	// To is the state entered.
	To S
	// Trigger is "create", "event", "timer" or "guard".
	Trigger string
	// Caller is the node that fired it, when code did.
	Caller string
	// At is when it happened.
	At time.Time
}

ChangeEvent describes one transition, for WorkflowService.OnTransition hooks: the entity, the event, and the states it left and entered.

type Command 

type Command[C, R any] struct {
	// contains filtered or unexported fields
}

Command changes something: a typed input, a typed result, and one handler — the one declared with it. Declare it with Service.Command; dispatch it with Command.Dispatch from any building block, which draws a dispatches edge from the caller; give it a route with Command.Expose. A command is internal until it is exposed: how one service has another change something.

A dispatch runs, in this order: the caller's user when the command asks for one (Auth, implied by Command.Allow) — an in-process dispatch carries its caller's and is not authenticated again —, the input's validate tags, the policies (RateLimit, RateLimitPerClient, Timeout, Bulkhead), the key (Command.Key), the transaction, the authorization (Command.Allow, then Command.Authorize), then the handler. A queued command (Queued) is checked at its dispatch, as its caller — its validate tags, its authorization, its key —, and handled by its queue's consumer, the policies around the handling, its key then its transaction around the handler.

A command is its unit of work (ADR 0004): its authorization and its handler run in one transaction (Transact), opened once its key is held, which holds its effects — a publish, a mail, a queued command's dispatch — until the commit. A failed command changes nothing and announces nothing; one dispatched inside another runs in its transaction. NoTransaction opts a command out.

func NewCommand 

func NewCommand[C, R any]() *Command[C, R]

NewCommand is a command no service declares yet: Service.Command makes one and declares it, which is how a product gets one.

func (*Command[C, R]) Allow 

func (c *Command[C, R]) Allow(policy authz.Policy, action, resource string) *Command[C, R]

Allow makes the command need a permission, as data: the app's policy must let the caller — its user, with the attributes its auth data gives when it implements AttrsProvider — do action to resource. The SDK's authz decides, and closes toward refusal: a role with no grant abstains, and an abstention is refused. Allow implies Auth; given twice, both permissions are needed. The refusal is 403 permission_denied, one sentence whatever the cause. 

var PlaceOrder = Service.Command("place-order", placeOrder).Allow(Policy, "place", "order")

func (*Command[C, R]) Authorize 

func (c *Command[C, R]) Authorize(fn func(context.Context, C) error) *Command[C, R]

Authorize gives the command a rule that needs the data — the ownership of what the input names, the membership of an organisation: fn sees the input and, through its context, the caller (UserID, AuthData), and returns nil, Forbidden, NotFound — to hide what exists — or an authz.Check of its own. It runs last before the handler, after Command.Allow, under the command's key; its refusal is 403 permission_denied, one sentence whatever the cause, and a NotFound or an Unauthenticated stays what it is. The static analysis reads fn as the command's code: the store it reads is the command's edge.

func (*Command[C, R]) Dispatch 

func (c *Command[C, R]) Dispatch(ctx context.Context, in C) (R, error)

Dispatch runs the command for the node ctx runs inside — in a span on the command, its caller's dispatches edge —, through its whole pipeline, and returns its result; a queued command returns once its queue accepted it. The caller's user goes with it.

func (*Command[C, R]) Expose 

func (c *Command[C, R]) Expose(route string, opts ...ExposeConfigurer) *Command[C, R]

Expose declares an endpoint that dispatches the command, on route — "METHOD /path/{param}" — with the options an endpoint takes (RateLimitPerClient, MaxBody, Name). It is an endpoint, named after the command — Name for a second exposure —, its request decoded as strictly as any, authenticated when the command asks for a user; the rest — validation, key, authorization — is the command's, so an exposed dispatch and an in-process one are checked alike. It answers 200 with the result, 204 for EmptyValue, 202 for a queued command.

An exposed command says who may run it: a permission (Command.Allow), a rule (Command.Authorize), or, when it declares neither, a marker that it is open on purpose — Anyone, or AnyUser for any signed-in user. The start refuses an exposure that says none of them. A command nobody exposes is internal: the code that needs it dispatches it.

func (*Command) ID 

func (n *Command) ID() string

ID returns the node's identifier in the product graph: "<service>/<kind>/<name>".

func (*Command[C, R]) Key 

func (c *Command[C, R]) Key(fn func(C) string) *Command[C, R]

Key names the entity the command is about: two runs of the command with one key never overlap — the second waits, within its context's deadline —, runs with different keys go at once, and a queued command whose key waits or runs is not queued again until it is handled or dead-lettered. A handler that dispatches its own command with its own key is refused (CodeCommandReentrant), never a deadlock. An input whose key is empty is refused. The key is the span's instance: the Studio filters the runs of one entity.

It is the SDK's lock, in the process: across a restart or between processes, one key can run twice — a handler stays idempotent.

type CommandConfigurer 

type CommandConfigurer interface {
	// contains filtered or unexported methods
}

CommandConfigurer configures a command: Queued; the options every operation takes — Auth, AuthOptional, RateLimit, RateLimitPerClient, Timeout, Bulkhead; and, for a queued one, MaxDeliveries and Parallelism.

func NoTransaction 

func NoTransaction() CommandConfigurer

NoTransaction runs a command outside a transaction of its own: its writes land as its handler makes them, and its effects leave when made — a failed command may have written or announced something. On the data directory and in memory, where a writing command's transaction takes the writer turn, it lets such commands run side by side. Dispatched inside another command, it still runs in that one's transaction.

func Queued 

func Queued() CommandConfigurer

Queued sends a command to the background. Dispatch returns once the command's own queue accepted it — a file queue under the data directory, memory without one —, and a consumer handles it, Parallelism at a time, retried up to MaxDeliveries attempts (5) — half a second after the first failure, the wait doubling after each, never more than a minute —, then dead-lettered; a dispatch that does not decode is dead-lettered at its first failure, since no retry makes it decode. It answers nothing: its result is EmptyValue, and exposed, it answers 202 Accepted.

Delivery is at least once: Queued is the product's promise that the handler tolerates a redelivery, and a Command.Key narrows the duplicates without removing them. The handler runs in the dispatcher's trace, as the user who dispatched it (UserID); what the auth handler said about that user is not queued. A queued command's input is a contract with the messages already queued: add a field, never rename one.

type CommandLineConfigurer 

type CommandLineConfigurer interface {
	// contains filtered or unexported methods
}

CommandLineConfigurer tunes a CLI command.

func DefaultCommand 

func DefaultCommand() CommandLineConfigurer

DefaultCommand makes the command Main's default: it runs with every argument when the first names no other command — neither one of the product's nor one of Main's (serve, help…) —, and with none when there is none. Main then never answers a usage error. One command of an app may be its default.

IFACE-OPAQUE: CLIOption is sealed — its one method is unexported — so only this package makes one, and a caller only passes it to CLI.

func FailSafe 

func FailSafe() CommandLineConfigurer

FailSafe makes the command's status always 0: a status line, a prompt hook, anything a shell runs on every keystroke must never fail the shell. A non-zero status, a start that fails and a panic are logged instead.

IFACE-OPAQUE: CLIOption is sealed — its one method is unexported — so only this package makes one, and a caller only passes it to CLI.

type DatabaseConfigurer 

type DatabaseConfigurer interface {
	// contains filtered or unexported methods
}

DatabaseConfigurer configures a database: Keeps, Migrations.

func Keeps 

func Keeps(things ...Keeper) DatabaseConfigurer

Keeps says what the database keeps: a service's stores, a store, a module's stores. The most precise wins: a store kept by name, then its service, then its module, then the default database — the one declared without Keeps —, then the data directory, then memory. InMemory wins over all of them, on the app as on a store. kit's data keys never live on SQLite: Keeps(kit.Privacy) there keeps its holds and its journal (Privacy).

type DatabaseURLValue 

type DatabaseURLValue struct {
	// Driver is the Go driver the engine speaks through: "pgx".
	Driver string
	// Address is where the server listens, host:port; a local socket's
	// path; empty for a file.
	Address string
	// Database is the database on the server, or the file.
	Database string
	// TLS is the TLS mode as the URL writes it — "verify-full", "true" —,
	// empty when the URL leaves it to the driver.
	TLS string
	// Plaintext says the mode the URL writes turns TLS off — sslmode=disable,
	// tls=false —: accepted, for a private network, and drawn "no TLS".
	Plaintext bool
	// Networked says the connection crosses a network, over TCP: outside
	// dev, its URL must write its TLS mode.
	Networked bool
}

DatabaseURLValue is what a database's URL points at, as its engine describes it for the graph, the Studio, the logs and every error: never a user, never a password, never a parameter.

type Delay 

type Delay interface {
	time.Duration | *SettingService[time.Duration]
}

Delay is how long a timer transition waits: a duration, or a setting that holds one — read when the delay is needed, so each environment can give its own.

type DeliveryOption 

type DeliveryOption interface {
	SubscriptionConfigurer
	CommandConfigurer
}

DeliveryOption configures a queue's deliveries: a subscription's, or a queued command's (MaxDeliveries, Parallelism).

func MaxDeliveries 

func MaxDeliveries(n int) DeliveryOption

MaxDeliveries is how many attempts a message gets before it is dead-lettered — a subscription's, or a queued command's. The default is 5.

IFACE-OPAQUE: the option is sealed — its method is unexported — so a caller only hands it to the declaration it configures.

func Parallelism 

func Parallelism(n int) DeliveryOption

Parallelism is how many messages are handled at once — a subscription's, or a queued command's. The default is 1.

IFACE-OPAQUE: the option is sealed — its method is unexported — so a caller only hands it to the declaration it configures.

type DiagnosticsError 

type DiagnosticsError struct {
	Diagnostics []model.Diagnostic
}

DiagnosticsError is returned by Start when declarations are wrong. It lists every problem at once, each with its position.

func (*DiagnosticsError) Error 

func (e *DiagnosticsError) Error() string

Error lists every problem the start found, one per line.

type Edit 

type Edit = model.Edit

Edit is one change between two versions of a record, in RFC 6902's words: Op is add, remove or replace, Path the RFC 6901 JSON pointer of the member it changes, From the value it had and To the value it has, as JSON. A secret member says it changed, never what: its From and To are empty.

type EmptyValue 

type EmptyValue struct{}

EmptyValue is the request or the response of an endpoint that has none. An endpoint answering EmptyValue replies 204 No Content.

type EndpointConfigurer 

type EndpointConfigurer interface {
	ExposeConfigurer
	// contains filtered or unexported methods
}

EndpointConfigurer configures an endpoint; each is an ExposeConfigurer too.

func MaxBody 

func MaxBody(bytes int64) EndpointConfigurer

MaxBody bounds the request body the endpoint reads. The default is DefaultMaxBody.

func Name 

func Name(name string) EndpointConfigurer

Name overrides the endpoint's name, which otherwise is its handler's function name, or its route when the handler is a function literal.

type EndpointService 

type EndpointService[Req, Resp any] struct {
	// contains filtered or unexported fields
}

EndpointService is an HTTP endpoint with a typed request and a typed response: what HTTP itself is about — a webhook a third party calls, say —, the exposure of a command or a query (Command.Expose, Query.Expose), or the implementation of a port (Service.Implement). A business operation is a command or a query, which other code runs with Command.Dispatch and Query.Ask and HTTP reaches through its exposure.

func NewEndpointService 

func NewEndpointService[Req, Resp any]() *EndpointService[Req, Resp]

NewEndpointService is an endpoint no service declares yet: Service.Endpoint makes one and declares it, which is how a product gets one.

func (*EndpointService[Req, Resp]) Call 

func (e *EndpointService[Req, Resp]) Call(ctx context.Context, req Req) (Resp, error)

Call runs the endpoint in-process, from another building block: the same validation, the same policies, the same handler, and a calls edge in the diagram from the caller to this endpoint. A port calls its implementation so. Services run each other's operations as commands and queries (Command.Dispatch, Query.Ask); calling a handler function directly works, but the product cannot see it.

func (*EndpointService) ID 

func (n *EndpointService) ID() string

ID returns the node's identifier in the product graph: "<service>/<kind>/<name>".

type Engine 

type Engine interface {
	// Dialect is the SQL the SDK speaks to it.
	Dialect() sql.Dialect
	// Describe says what url points at — the driver, host and port, the
	// database, the TLS mode as written — for the graph and the logs: never
	// a user, never a password.
	Describe(url secret.Value) (DatabaseURLValue, error)
	// Open opens the pool url names. Before each new connection it asks
	// current for the URL as it is now.
	Open(url secret.Value, current func(context.Context) (secret.Value, error)) (*stdsql.DB, error)
}

Engine is an SQL engine a database runs on. An engine module returns one — github.com/kitsunium/sdk/framework/connectors/postgres, …/mysql, …/sqlite —; kit calls it when the database starts. Like an SDK port, it grows by sibling interfaces, never by a method.

type Erasure 

type Erasure = model.Erasure

Erasure is what kit.Erase did, store by store.

func Erase 

func Erase(ctx context.Context, reason string, ids ...string) (Erasure, error)

Erase erases every record whose subject is one of ids, in every store of the app, as its retention would — or deletes it where the store says kit.DeleteOnErasure — and folds the stores it wrote, so that what it overwrote leaves their files. A held record is left in place, and the result says so: it lists, per store, what was erased, deleted and held. Telling the recipients (GDPR art. 19) is the product's job; the register lists them. reason is journaled.

What kit seals at rest, it erases cryptographically too (ADR 0006 §4): a held record is moved under a data key of its own, then the data key of each identity, and every data key the erased records were sealed under, is destroyed — every copy of what they sealed stops opening: a store's former values, a dead letter, a backup. An erasure that failed in a store destroys nothing: its retry does.

type Error 

type Error struct {
	// Status is the HTTP status.
	Status int
	// Code is a stable, snake_case identifier a client can branch on.
	Code string
	// Message is wire-safe text for the caller.
	Message string
	// Violations detail an invalid request, one per failed rule.
	Violations []ViolationMessage
	// contains filtered or unexported fields
}

Error is an error a product returns to its callers. Message travels on the wire; the cause attached with Error.Wrap is logged and never sent.

Return one from a handler to choose the HTTP status and the message the caller reads. Any other error becomes a 500 whose body says nothing about it: an error message is the classic place a secret leaks from.

func Conflict 

func Conflict(message string) *Error

Conflict reports a request the resource's current state refuses (409).

func Forbidden 

func Forbidden(message string) *Error

Forbidden reports a caller who may not do this (403).

func Invalid 

func Invalid(message string) *Error

Invalid reports a request the caller must change before retrying (400).

func NewError 

func NewError(status int, code, message string) *Error

NewError is an error answered with the HTTP status, carrying the wire code and the message a caller reads.

func NotFound 

func NotFound(message string) *Error

NotFound reports that the addressed resource does not exist (404).

func Unauthenticated 

func Unauthenticated(message string) *Error

Unauthenticated reports a caller who did not prove who they are (401).

func Unavailable 

func Unavailable(message string) *Error

Unavailable reports a transient failure worth retrying later (503).

func (*Error) Error 

func (e *Error) Error() string

Error renders the code and the message. It never renders the cause.

func (*Error) Unwrap 

func (e *Error) Unwrap() error

Unwrap returns the cause, so errors.Is and errors.As see through an Error.

func (*Error) Wrap 

func (e *Error) Wrap(cause error) *Error

Wrap attaches the underlying cause, for the logs. It returns a copy.

type ExposeConfigurer 

type ExposeConfigurer interface {
	// contains filtered or unexported methods
}

ExposeConfigurer configures an exposure (Command.Expose, Query.Expose): every EndpointConfigurer — Name, MaxBody, RateLimitPerClient… — and the markers that say who may run an operation declaring no rule of its own: Anyone, AnyUser.

func AnyUser 

func AnyUser() ExposeConfigurer

AnyUser says that an exposure is open to any signed-in user, on purpose: its operation asks for a user (Auth) and declares no permission and no rule — its handler reads UserID and keeps to what that user owns. 

var MyOrders = Service.Query("my-orders", myOrders, kit.Auth()).Expose("GET /orders", kit.AnyUser())

It adds no authentication of its own: an exposure authenticates as its operation asks, so the operation declares Auth.

func Anyone 

func Anyone() ExposeConfigurer

Anyone says that an exposure is open to everyone, on purpose: its operation declares no permission and no rule, and whoever reaches the route may run it — a public form, say. It says so on the exposure's node, where the diagram and the API page read it. An exposure whose operation declares no rule refuses the start unless it says this, or AnyUser. 

var Report = Service.Command("report", file).Expose("POST /reports", kit.Anyone())

It adds no authentication: an operation that asks for a user (Auth) takes AnyUser instead, and one with AuthOptional still knows the caller who signed in.

type FieldRefValue 

type FieldRefValue struct {
	// Store is the store's node ID.
	Store string `json:"store"`
	// Path is the field's JSON pointer in the entity: "/body". A "*"
	// stands for every element of an array or every value of a map:
	// "/replies/*/body".
	Path string `json:"path"`
	// Class is the field's class; "" when it is unclassified.
	Class string `json:"class,omitempty"`
	// Subject is the pointer of the store's subject — for moderated
	// content, its author — or "" when the store has none.
	Subject string `json:"subject,omitempty"`
}

FieldRefValue is one field of one store that carries a mark: where the field is, and what its tag says of it.

type Former 

type Former = model.Former

Former is one former value of a field that keeps its history: what it was, until when, and who replaced it.

type Frontend 

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

Frontend is static assets the product serves: a single page application, a documentation site. Requests the page makes to the product's endpoints are attributed to it in the diagram.

func (*Frontend) ID 

func (n *Frontend) ID() string

ID returns the node's identifier in the product graph: "<service>/<kind>/<name>".

type Job 

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

Job is scheduled work: a piece of the daemon's internal loop. It runs on the SDK scheduler, whose decisions about time are documented rather than emergent: a fire that is due while the previous run of the same job is still going is skipped and counted, and a missed deadline is skipped and counted, never caught up.

func (*Job) ID 

func (n *Job) ID() string

ID returns the node's identifier in the product graph: "<service>/<kind>/<name>".

type Keeper 

type Keeper interface {
	// contains filtered or unexported methods
}

Keeper is what a database keeps: a service — every store it declares —, a store, or a module (ADR 0008) — every store of its services.

type ListenHandler 

type ListenHandler func(ctx context.Context, conn *ipc.Conn) error

ListenHandler serves one connection of a Listener until it returns; the connection is closed after it. conn.Peer says who connected, as the kernel says where it can (pkg/v1/proc/ipc).

type Listener 

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

Listener is an inbound port that is not HTTP: a private socket on this machine — a Unix socket in a directory only the product's account can reach, the kernel naming the peer on Linux (ADR 0148) — speaking a versioned contract. It is how a daemon profile serves its clients, and how two process roles of one binary talk (D22): through the contract, never through each other's code.

func NewListener 

func NewListener(contract string, handler ListenHandler) *Listener

NewListener is a listener no service declares yet, speaking contract and served by handler: Service.Listen makes one and declares it, which is how a product gets one.

func (*Listener) Dial 

func (l *Listener) Dial(ctx context.Context) (*ipc.Conn, error)

Dial connects to the listener as a client of the same account would: the same checks, from the same configuration. A test and a sibling role use it.

func (*Listener) DialIn 

func (l *Listener) DialIn(ctx context.Context, product string) (*ipc.Conn, error)

DialIn connects to the listener as run in product, from another process — a client role of the same binary —: the path SocketPathIn computes, the checks Dial makes.

func (*Listener) ID 

func (n *Listener) ID() string

ID returns the node's identifier in the product graph: "<service>/<kind>/<name>".

func (*Listener) Path 

func (l *Listener) Path() string

Path is where the listener listens while the app runs; "" otherwise.

func (*Listener) SocketPathIn 

func (l *Listener) SocketPathIn(product string) (string, error)

SocketPathIn is where the listener's socket lies in product — the binary's name for a role of one, else the app's —: its SocketPath, else <runtime dir of product>/<service>-<name>.sock, with SocketPer's key before the extension. A client of another process role computes the daemon's path with it.

type ListenerConfigurer 

type ListenerConfigurer interface {
	// contains filtered or unexported methods
}

ListenerConfigurer tunes a listener.

func AllowPeers 

func AllowPeers(uids, gids []int) ListenerConfigurer

AllowPeers admits accounts besides the product's own: an on-call group declared at deployment. The kernel checks them where it names the peer; the socket's directory must still let them through, which is the deployment's to arrange.

IFACE-OPAQUE: ListenerOption is sealed — its one method is unexported — so only this package makes one, and a caller only passes it to Listen.

func SocketPath 

func SocketPath(path string) ListenerConfigurer

SocketPath places the listener's socket at path — absolute, at most 103 bytes — instead of <runtime dir of the app>/<service>-<name>.sock.

IFACE-OPAQUE: ListenerOption is sealed — its one method is unexported — so only this package makes one, and a caller only passes it to Listen.

func SocketPer 

func SocketPer(scopes ...ScopeValue) ListenerConfigurer

SocketPer names the listener's socket after the value of scopes in this process — <runtime dir of the app>/<service>-<name>-<key>.sock, the key being ScopeKey's —: one daemon per user, per executable, per configuration directory. A client finds it with SocketPathIn or DialIn, which compute the same key from the same declaration.

IFACE-OPAQUE: ListenerOption is sealed — its one method is unexported — so only this package makes one, and a caller only passes it to Listen.

type LockWaiter added in v0.24.0 

type LockWaiter interface {
	// OpenWaiting opens the pool url names, as Open does, its connections
	// waiting wait for a lock when url writes no wait of its own.
	OpenWaiting(url secret.Value, current func(context.Context) (secret.Value, error), wait time.Duration) (*stdsql.DB, error)
}

LockWaiter is an Engine whose connections wait a bounded time for a lock another connection holds — SQLite's busy timeout —, a sibling of Engine (ADR 0178 C2). kit opens such an engine's pool with OpenWaiting instead of Open, and gives it a wait under <name>-timeout, so that a lost race on the lock comes back as the engine's refusal before the call's own deadline. An engine that does not implement it keeps its own wait.

type Loop 

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

Loop is a declared loop of the daemon: kit owns the wait, the product owns the work. Its wake sources — a period, a deadline the product computes, a topic — are data, so the diagram draws exactly what wakes it; kit runs it on its own goroutine, one run at a time, observes every run, and restarts it after a panic.

func NewLoop 

func NewLoop(run func(context.Context, WakeEvent) error) *Loop

NewLoop is a loop no service declares yet, whose runs are run: Service.Loop makes one and declares it, which is how a product gets one.

func (*Loop) ID 

func (n *Loop) ID() string

ID returns the node's identifier in the product graph: "<service>/<kind>/<name>".

func (*Loop) Nudge 

func (l *Loop) Nudge()

Nudge wakes the loop now, as if its deadline had come. The run's reason is model.WakeManual; a nudge also cuts short the backoff after a failure. It does nothing while the loop is not running.

type LoopConfigurer 

type LoopConfigurer interface {
	// contains filtered or unexported methods
}

LoopConfigurer configures a declared loop.

func WakeAt 

func WakeAt(next func(context.Context) (time.Time, bool)) LoopConfigurer

WakeAt wakes the loop at the time next returns, asked again after every run; false means "no deadline for now". It is how a loop sleeps exactly until its next piece of work — the next reminder due — rather than polling.

IFACE-OPAQUE: the option is sealed — its method is unexported — so a caller only hands it to the declaration it configures.

func WakeEvery 

func WakeEvery(d time.Duration) LoopConfigurer

WakeEvery wakes the loop every d.

IFACE-OPAQUE: the option is sealed — its method is unexported — so a caller only hands it to the declaration it configures.

func WakeOn 

func WakeOn[T any](topic *TopicService[T]) LoopConfigurer

WakeOn wakes the loop whenever a message is published on topic. It is a nudge, not a subscription: the loop is not handed the message and wakes once for a burst — it re-reads the state it works on.

IFACE-OPAQUE: the option is sealed — its method is unexported — so a caller only hands it to the declaration it configures.

type Mailer 

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

Mailer is outbound mail: a durable outbox and the transport that empties it. Mailer.Send only queues — it returns once the message is safely in the outbox — and the mailer's own loop hands each message to the transport, retrying a failure and dead-lettering a message after its last attempt.

The transport is the SDK's mail package: SMTP when the mail connector's secret smtp-url is set — KIT_SMTP_URL, smtp://user:password@host:587?tls= starttls|implicit|none — and otherwise the capture transport, which keeps every message for the Studio's mailbox and for tests (Mailer.Captured) and delivers nothing. Outside dev, the capture transport is reported as a warning. The URL is read again before every delivery: replacing it where it lives — a new version in the store, a new file behind KIT_SMTP_URL_FILE — takes effect at the next mail.

func NewMailer 

func NewMailer() *Mailer

NewMailer is a mailer no service declares yet, with the default attempts: Service.Mailer makes one and declares it, which is how a product gets one.

func (*Mailer) Captured 

func (m *Mailer) Captured() []model.MailMessage

Captured returns the messages the capture transport kept, oldest first: what a test reads a verification link from. It is empty with SMTP. A mail appears once the outbox has delivered it — shortly after Send.

func (*Mailer) ID 

func (n *Mailer) ID() string

ID returns the node's identifier in the product graph: "<service>/<kind>/<name>".

func (*Mailer) Send 

func (m *Mailer) Send(ctx context.Context, msg mail.Message) (string, error)

Send validates msg with the SDK's mail rules — a header carrying a line break, an unusable address, an empty body are refused here, not at delivery — and puts it in the outbox. It returns the message's outbox ID. Inside a transaction (Transact, a command's) the mail waits for the commit — a rollback drops it —, and the ID returned at once is the one the mail keeps. When the outbox lives on the transaction's database — the one that keeps the mailer's service, by a store's rules — the mail is written in the transaction, sealed, just before it commits: it exists if and only if the transaction commits, the mailbox hears of it after the commit, and an outbox that refuses it fails the transaction. Elsewhere it is put in the outbox after the commit.

A message without a sender gets the mailer's (From); without a date, the app's time; without a Message-ID, one made of its outbox ID, which every attempt keeps, so a receiver can tell a retried delivery from a new mail.

type MailerConfigurer 

type MailerConfigurer interface {
	// contains filtered or unexported methods
}

MailerConfigurer configures a mailer.

func From 

func From(name, addr string) MailerConfigurer

From sets the sender of every message that names none.

IFACE-OPAQUE: the option is sealed — its method is unexported — so a caller only hands it to the declaration it configures.

func MailAttempts 

func MailAttempts(n int) MailerConfigurer

MailAttempts is how many deliveries a message gets before it is dead-lettered. The default is 6, backing off from one second.

IFACE-OPAQUE: the option is sealed — its method is unexported — so a caller only hands it to the declaration it configures.

type Mark 

type Mark string

Mark is what a module looks for in the product's fields: kit.Personal, kit.Special or kit.Moderated. There is no mark for public or secret: there is nothing to find in the first, and nothing may watch the second. 

const (
	// Personal marks a field that holds data about a person: personal,
	// special, or a record's subject.
	Personal Mark = "personal"
	// Special marks a field of GDPR art. 9(1) or art. 10.
	Special Mark = "special"
	// Moderated marks content others see and a moderator may act on.
	Moderated Mark = "moderated"
)

The marks.

type Module 

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

Module is a set of services a product mounts as one: NewModule declares it, App.With or Mount mounts it.

func NewModule 

func NewModule(name, doc string, parts ...ModuleConfigurer) *Module

NewModule declares a module named name — lower-case letters, digits and dashes, starting with a letter; "kit", "external" and "schema" are kit's — that doc describes, made of parts: its services, which it adopts, the modules it requires (Requires), and the migrations of the data it keeps outside kit's stores (Migrations), run on the database that keeps it. Declare it as a package-level variable of the one package a product imports: 

var Module = kit.NewModule("moderation",
	"Reports and moderation under the DSA.\n\nfr: Signalements et modération selon le DSA.",
	intake.Service, desk.Service, kit.Requires(identity.Module))

A service a module lists is its own: what it declared so far is renamed, and what it declares later is born qualified. Listing a service links its package; a service is a module's only, and a module's services take declarations from the module's own Go module only.

func (*Module) Name 

func (m *Module) Name() string

Name returns the module's name.

func (*Module) Prefix 

func (m *Module) Prefix() string

Prefix is where the app running the module serves its routes — "/<name>/" unless the mount says otherwise — and its default before an app runs it. A module's user interface, built with relative URLs, finds its API there.

type ModuleConfigurer 

type ModuleConfigurer interface {
	// contains filtered or unexported methods
}

ModuleConfigurer is what a module is made of: its services, the modules it requires (Requires), and the migrations of the data it keeps outside kit's stores (Migrations).

func Requires 

func Requires(other *Module) ModuleConfigurer

Requires says the module needs other: an app that mounts the module and not other mounts other at its defaults, and starts it first. The Go import this takes makes a cycle impossible. A collaboration a module can do without is a port with a fallback instead (Fallback).

type MountConfigurer 

type MountConfigurer interface {
	// contains filtered or unexported methods
}

MountConfigurer configures the mount of a module: Prefix, Bind.

func Prefix 

func Prefix(prefix string) MountConfigurer

Prefix serves a module's routes under prefix — "/trust/" — instead of "/<module>/"; "/" shares the product's route space, where a route both declare is refused as any two are. A prefix starts and ends with '/', and never lies under /_kit/.

type Operation 

type Operation[Req, Resp any] interface {
	// contains filtered or unexported methods
}

Operation takes a typed request and answers a typed response: an endpoint, a port — and, with ADR 0005, a command or a query. It is what Fallback and Bind give a port, and what Replace replaces in a test; a request or a response of other types does not compile. Its methods are unexported: only kit implements it.

Every operation is a node of the graph, and runs in a span of its own through its whole pipeline — authentication, validation, policies, the Studio's mocks — whoever calls it.

type OperationOption 

type OperationOption interface {
	EndpointConfigurer
	CommandConfigurer
	QueryConfigurer
}

OperationOption configures an endpoint, a command or a query alike: the authentication it asks for (Auth, AuthOptional) and the policies in front of its handler (RateLimit, RateLimitPerClient, Timeout, Bulkhead).

func Auth 

func Auth() OperationOption

Auth makes an endpoint require an authenticated caller: the app's auth handler runs first, and a request without valid credentials is answered 401 before the handler runs. A command or a query that asks for one is refused 401 when its caller carries no user: an in-process dispatch carries its caller's, and is not authenticated again.

IFACE-OPAQUE: the option is sealed — its method is unexported — so a caller only hands it to the declaration it configures.

func AuthOptional 

func AuthOptional() OperationOption

AuthOptional runs the app's auth handler when the request carries credentials, and serves anonymous callers too: UserID tells which.

IFACE-OPAQUE: the option is sealed — its method is unexported — so a caller only hands it to the declaration it configures.

func Bulkhead 

func Bulkhead(maxConcurrent int) OperationOption

Bulkhead caps how many requests the handler serves at once; the overflow answers 503. It is the SDK's resilience bulkhead.

IFACE-OPAQUE: the option is sealed — its method is unexported — so a caller only hands it to the declaration it configures.

func RateLimit 

func RateLimit(perSecond float64, burst int) OperationOption

RateLimit puts a token bucket in front of the handler: perSecond tokens a second, up to burst at once. An empty bucket answers 429 at once. It is the SDK's resilience rate limiter.

IFACE-OPAQUE: the option is sealed — its method is unexported — so a caller only hands it to the declaration it configures.

func RateLimitPerClient 

func RateLimitPerClient(perSecond float64, burst int) OperationOption

RateLimitPerClient gives every client of an endpoint a token bucket of its own: perSecond tokens a second, up to burst at once. A client is the authenticated user when there is one, and the client's address otherwise (ClientIP); in-process calls through EndpointService.Call share one bucket. One client emptying its bucket is answered 429; the others are not — which is what a sign-in endpoint needs, where one shared bucket would let a single client lock everybody out.

Buckets unused for ten minutes are forgotten, and at most 10 000 are kept: the least recently used goes first. It is the SDK's keyed rate limiter.

IFACE-OPAQUE: the option is sealed — its method is unexported — so a caller only hands it to the declaration it configures.

func Timeout 

func Timeout(d time.Duration) OperationOption

Timeout cancels the handler's context after d and answers 504. It is the SDK's resilience timeout.

IFACE-OPAQUE: the option is sealed — its method is unexported — so a caller only hands it to the declaration it configures.

type PasswordConfigurer 

type PasswordConfigurer interface {
	// contains filtered or unexported methods
}

PasswordConfigurer configures a password policy: MinLength, NotReused, NotCommon.

func MinLength 

func MinLength(n int) PasswordConfigurer

MinLength refuses a password shorter than n characters, counted as NIST counts them: one per Unicode code point. The default is 15, NIST's figure for a password used alone; 8 is the floor NIST allows with a second factor, and a smaller n is refused. There is no composition rule, ever: NIST says SHALL NOT.

IFACE-OPAQUE: the option is sealed — its method is unexported — so a caller only hands it to the declaration it configures.

func NotCommon 

func NotCommon() PasswordConfigurer

NotCommon refuses a password among the ten thousand most common ones — the SDK's password.IsCommon, which compares them without regard to case —: the blocklist NIST SP 800-63B-4 requires a verifier to check, beyond the three thousand OWASP ASVS 5.0 (6.2.4) asks for. Every policy checks it (ADR 0007 §2: on by default once the SDK has the list); the option says so where a policy is declared. Beside NIST's fifteen characters the list has little left to refuse; beside a shorter MinLength, it matters.

IFACE-OPAQUE: the option is sealed — its method is unexported — so a caller only hands it to the declaration it configures.

func NotReused 

func NotReused(n int) PasswordConfigurer

NotReused refuses a password that the current hash, or any of the n former ones, verifies — n from 1 to 100. It is a compliance policy, off by default: PCI DSS asks for it, OWASP ASVS 4.0.3 asks most products not to impose it. kit keeps the field's last n hashes, so it implies history=n, and a tag whose history is smaller than n is refused.

IFACE-OPAQUE: the option is sealed — its method is unexported — so a caller only hands it to the declaration it configures.

type PasswordPolicyService 

type PasswordPolicyService[T any] struct {
	// contains filtered or unexported fields
}

PasswordPolicyService is the policy of one secret field that holds a password's hash: how long a password is at least, and how many former passwords it refuses. StoreService.Passwords declares it; Set, Change and Verify apply it.

func (*PasswordPolicyService[T]) Change 

func (p *PasswordPolicyService[T]) Change(ctx context.Context, key string, current, next []byte) error

Change changes the password of the record under key: it verifies the current password first, as Symfony's UserPassword does — a wrong one is an Invalid error —, then sets next as Set does.

func (*PasswordPolicyService[T]) Set 

func (p *PasswordPolicyService[T]) Set(ctx context.Context, key string, password []byte) error

Set sets the password of the record under key — a reset flow, behind a reset token: it checks the policy — the length, the most common passwords, and with NotReused the former passwords —, hashes the password with the SDK's password.Hash and stores the hash; the hash it replaces goes to the field's history. A password the policy refuses is an Invalid error, which says it was used recently, never which one; a missing record is a NotFound.

func (*PasswordPolicyService[T]) Verify 

func (p *PasswordPolicyService[T]) Verify(ctx context.Context, key string, password []byte) (bool, error)

Verify reports whether password is the one of the record under key, for a login, with the SDK's constant-time Verify. When the stored hash is weaker than the SDK's policy now (password.NeedsRehash), kit stores it again, hashed anew: the same password, so no former value. A key with no record — or a record with no password yet — costs what a wrong password costs, and answers false.

type PersonalData 

type PersonalData = model.PersonalData

PersonalData is a person's data as kit.Export gives it.

func Export 

func Export(ctx context.Context, ids ...string) (PersonalData, error)

Export returns every record whose subject is one of ids, in every store of the app: each without its secret members, with the former values its fields keep (ADR 0007) — never a secret field's — and the versions its store keeps of it, without their secret members, and per store what GDPR art. 15(1) asks beside the data — the purpose, the retention and the recipients inside the product. A held record is exported like any other. The result is JSON, structured and machine-readable (art. 20); keeping the month of art. 12(3) is the product's job, and so is deciding who may call it.

A person known under several identities — a user's ID in one store, an e-mail address in another — is found by giving all of them. ctx must run inside the app: an endpoint's, a job's, a loop's.

type PortConfigurer 

type PortConfigurer[Req, Resp any] interface {
	// contains filtered or unexported methods
}

PortConfigurer configures a port: Fallback.

func Fallback 

func Fallback[Req, Resp any](op Operation[Req, Resp]) PortConfigurer[Req, Resp]

Fallback gives a port an implementation from its own side, which it calls when the app binds nothing else: an endpoint — or, with ADR 0005, a command or a query — of the port's types. A port given here is refused when the app starts. 

var Enforcer = Service.Port[Measure, Applied]("enforcer", kit.Fallback(QueueAPI))

IFACE-OPAQUE: the option is sealed — its method is unexported — so a caller only hands it to the declaration it configures.

type PortService 

type PortService[Req, Resp any] struct {
	// contains filtered or unexported fields
}

PortService is an operation a service needs and does not implement: a typed request, a typed response, a name. Declare it with Service.Port, and call it with PortService.Call as an endpoint is called: validated, observed, drawn.

What a port calls is decided when the app starts, by one rule the static analysis shares: the app's Bind, else the one Service.Implement among the services the app mounts, else the port's own Fallback. The start refuses a port it cannot bind, with every other problem at once.

A port is how a service reaches what it cannot import — a module its host's content, a service another that imports it — the consumer owning the contract.

func NewPortService 

func NewPortService[Req, Resp any]() *PortService[Req, Resp]

NewPortService is a port no service declares yet: Service.Port makes one and declares it, which is how a product gets one.

func (*PortService[Req, Resp]) Call 

func (p *PortService[Req, Resp]) Call(ctx context.Context, req Req) (Resp, error)

Call runs what the port is bound to: in a span on the port — the caller's calls edge — then in the bound operation's own span, through its whole pipeline, carrying the caller's user as EndpointService.Call does.

func (*PortService) ID 

func (n *PortService) ID() string

ID returns the node's identifier in the product graph: "<service>/<kind>/<name>".

type Query 

type Query[Q, R any] struct {
	// contains filtered or unexported fields
}

Query reads and changes nothing: a typed input, a typed result, and one handler — the one declared with it. Declare it with Service.Query; ask it with Query.Ask from any building block, which draws an asks edge from the caller; give it a route with Query.Expose. A query is internal until it is exposed: how one service reads what another keeps. The static analysis warns of a query whose code writes a store, fires a workflow, publishes, sends a mail or dispatches a command.

A question runs, in this order: the caller's user when the query asks for one (Auth, implied by Query.Allow), the input's validate tags, the policies, the authorization (Query.Allow, then Query.Authorize), then the handler, on the caller's goroutine.

func NewQuery 

func NewQuery[Q, R any]() *Query[Q, R]

NewQuery is a query no service declares yet: Service.Query makes one and declares it, which is how a product gets one.

func (*Query[Q, R]) Allow 

func (q *Query[Q, R]) Allow(policy authz.Policy, action, resource string) *Query[Q, R]

Allow makes the query need a permission, as data: the app's policy must let the caller — its user, with the attributes its auth data gives when it implements AttrsProvider — do action to resource. It implies Auth; given twice, both permissions are needed. The refusal is 403 permission_denied, one sentence whatever the cause.

func (*Query[Q, R]) Ask 

func (q *Query[Q, R]) Ask(ctx context.Context, in Q) (R, error)

Ask runs the query for the node ctx runs inside — in a span on the query, its caller's asks edge —, through its whole pipeline, and returns its result. The caller's user goes with it.

func (*Query[Q, R]) Authorize 

func (q *Query[Q, R]) Authorize(fn func(context.Context, Q) error) *Query[Q, R]

Authorize gives the query a rule that needs the data: fn sees the input and, through its context, the caller, and returns nil, Forbidden, NotFound — to hide what exists — or an authz.Check of its own. It runs last before the handler, after Query.Allow; its refusal is 403 permission_denied, one sentence whatever the cause, and a NotFound or an Unauthenticated stays what it is.

func (*Query[Q, R]) Expose 

func (q *Query[Q, R]) Expose(route string, opts ...ExposeConfigurer) *Query[Q, R]

Expose declares an endpoint that asks the query, on route, with the options an endpoint takes (RateLimitPerClient, MaxBody, Name): named after the query, authenticated when the query asks for a user, the rest of the pipeline the query's. It answers 200 with the result, 204 for EmptyValue.

An exposed query says who may ask it: a permission (Query.Allow), a rule (Query.Authorize), or, when it declares neither, a marker that it is open on purpose — Anyone, or AnyUser for any signed-in user. The start refuses an exposure that says none of them. A query nobody exposes is internal: the code that needs it asks it.

func (*Query) ID 

func (n *Query) ID() string

ID returns the node's identifier in the product graph: "<service>/<kind>/<name>".

type QueryConfigurer 

type QueryConfigurer interface {
	// contains filtered or unexported methods
}

QueryConfigurer configures a query: the options every operation takes — Auth, AuthOptional, RateLimit, RateLimitPerClient, Timeout, Bulkhead.

type RecordsService 

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

RecordsService is one store's records without their type. Get returns a record without its secret members; Keys lists the records' keys, to a module that watches the store; EraseFields and Delete take a reason and are refused on a held record. Each call is a span on the store's node and an entry in the privacy journal.

func NewRecordsService 

func NewRecordsService(port recordsPort) RecordsService

NewRecordsService is the records of the store port reaches: App.Records and RecordsOf make one for a store the app mounts.

func RecordsOf 

func RecordsOf(ctx context.Context, store string) (RecordsService, error)

RecordsOf is App.Records for code the app runs and that does not hold it — a module's watch, its endpoints: the records port of the store whose node ID is store, in the app ctx runs in. Outside a running app it is an Unavailable error. 

func Screen(ctx context.Context, w kit.Written) error {
	recs, err := kit.RecordsOf(ctx, w.Store)
	…
	record, err := recs.Get(ctx, w.Key)

func (RecordsService) Delete 

func (r RecordsService) Delete(ctx context.Context, key, reason string) error

Delete removes the record under key; a held record is a Conflict.

func (RecordsService) EraseFields 

func (r RecordsService) EraseFields(ctx context.Context, key, reason string, paths ...string) error

EraseFields clears the fields at paths — pointers as FieldRefValue gives them — in the record under key: the final removal of a moderated field. A path that names no classified field is an Invalid error; a held record is a Conflict.

func (RecordsService) Get 

func (r RecordsService) Get(ctx context.Context, key string) (json.RawMessage, error)

Get returns the record under key as JSON, its secret members left out.

func (RecordsService) Keys added in v0.26.0 

func (r RecordsService) Keys(ctx context.Context) iter.Seq2[string, error]

Keys yields the key of every record the store holds, in key order, and nothing of a record: what a watch reads to catch up on the writes it may have missed. It is offered only to a module one of whose watches the store feeds — any other caller, code outside a module's node included, is refused with a Forbidden error (CodeRecordsKeys) —, and each listing is one entry in the privacy journal, however many keys it yields. A record in the store's trash is not listed. A failure is yielded once, with an empty key, and ends the listing.

type RevisionEvent 

type RevisionEvent[T any] struct {
	Number  uint64
	At      time.Time
	By      string
	Command string
	Value   T
}

RevisionEvent is one version of a record a store with Revisions keeps: its number — from 1, never given twice while the record exists —, when the write that made it ran, on the app's clock, zero for a record stored before its store kept revisions; who made it — the caller's UserID, empty for a write with no user —; which command made it — its node ID, empty outside a command —; and the record as it was, its secret members zeroed.

type Routine 

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

Routine is a loop written by hand: a function that runs until its context ends. kit starts it with the app, cancels its context on shutdown and waits for it, restarts it after an error or a panic — backing off from one second to one minute — and reads its select statements to draw what it waits on.

func (*Routine) ID 

func (n *Routine) ID() string

ID returns the node's identifier in the product graph: "<service>/<kind>/<name>".

type ScopeValue 

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

ScopeValue is one part of a path computed at the start: the user, the executable, a configuration directory. Two processes share a singleton or a socket when every scope gives them the same value.

func PerEnv 

func PerEnv(name, fallback string) ScopeValue

PerEnv is the environment variable name, else fallback when it is unset or empty; a leading "~/" in either is the user's home directory. The status line's is PerEnv("CLAUDE_CONFIG_DIR", "~/.claude"): one daemon per Claude configuration.

type Secret 

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

Secret is a secret the product declares: provided by the operator — an SMTP URL, an API token — or generated by kit — a signing or sealing key — and rotated on its schedule.

func NewSecret 

func NewSecret() *Secret

NewSecret is a secret no service declares yet, rotated and kept as by default: Service.Secret makes one and declares it, which is how a product gets one.

func (*Secret) ID 

func (n *Secret) ID() string

ID returns the node's identifier in the product graph: "<service>/<kind>/<name>".

func (*Secret) Open 

func (s *Secret) Open(ctx context.Context, box, aad []byte) ([]byte, error)

Open decrypts a box any kept version sealed, with the aad it was sealed with. A box no kept version opens — forged, altered, or sealed by a version pruned since — is refused with an error errors.Is matches with secret.SealInvalid.

func (*Secret) Present 

func (s *Secret) Present(ctx context.Context) (bool, error)

Present reports whether the secret is set now, where it lives: false, and no error, when an Optional secret is given nowhere — which the product answers by leaving off what needs it. An error says its store could not be read. A secret the start required is present, unless the operator took it back since. 

if ok, err := OpenAIKey.Present(ctx); err != nil || !ok {
	return Verdict{}, err // no key, no automatic screening
}

func (*Secret) Seal 

func (s *Secret) Seal(ctx context.Context, plaintext, aad []byte) ([]byte, error)

Seal encrypts plaintext under the secret's current version, binding aad: data that travels beside the box in the clear and must come back unchanged for the box to open.

func (*Secret) Sign 

func (s *Secret) Sign(ctx context.Context, message []byte) ([]byte, error)

Sign signs message with the secret's current version.

func (*Secret) Value 

func (s *Secret) Value(ctx context.Context) (secret.Value, error)

Value returns the secret's current version. A provided secret is read where it lives at every call.

func (*Secret) Verify 

func (s *Secret) Verify(ctx context.Context, message, signature []byte) error

Verify reports whether a kept version signed message: nil when one did, and an error errors.Is matches with secret.SignatureInvalid when none did.

type SecretConfigurer 

type SecretConfigurer interface {
	// contains filtered or unexported methods
}

SecretConfigurer configures a secret.

func Generated 

func Generated(bytes int) SecretConfigurer

Generated makes the secret kit's to make: versions of bytes random bytes — 32 for a key — the first made on the first start, a new one every 30 days, the last 3 kept, unless RotateEvery and KeepVersions say otherwise.

IFACE-OPAQUE: the option is sealed — its method is unexported — so a caller only hands it to the declaration it configures.

func KeepVersions 

func KeepVersions(n int) SecretConfigurer

KeepVersions is how many versions of a generated secret a rotation leaves, the new one included: at least 2, so that what the version it replaces sealed or signed still opens and verifies. Cover the longest-lived box or signature in flight: its lifetime divided by the interval, plus one.

IFACE-OPAQUE: the option is sealed — its method is unexported — so a caller only hands it to the declaration it configures.

func Optional 

func Optional() SecretConfigurer

Optional makes a provided secret one the product can do without — the key of a feature that stays off while nobody gives it. A start where it is set nowhere goes on; Secret.Present says whether it is set now, and a use of it while it is absent — Secret.Value, Seal, Open, Sign or Verify — answers an error errs.HasCode matches with CodeSecretMissing. It is read where it lives at every use, as every provided secret is: given later — `secrets set` in the environment's store, a new content in the file its _FILE variable names —, it is found at its next use. A generated secret is kit's to make and never absent: Optional with Generated is refused.

IFACE-OPAQUE: the option is sealed — its method is unexported — so a caller only hands it to the declaration it configures.

func RotateEvery 

func RotateEvery(d time.Duration) SecretConfigurer

RotateEvery is how often kit makes a new version of a generated secret.

IFACE-OPAQUE: the option is sealed — its method is unexported — so a caller only hands it to the declaration it configures.

type Service 

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

Service is a bounded context of the product: it owns its building blocks — endpoints, stores, topics, subscriptions, workflows, jobs, frontends — and is the unit an App mounts. Declare one per package, as a package-level variable, and declare its building blocks through its methods: 

var Service = kit.NewService("todos", "The todo list.")
var Todos = Service.Store("todos", func(t Todo) string { return t.ID })
var _ = Service.Endpoint("GET /todos", List)

Declaring never fails: a mistake — a malformed route, a duplicate name — is recorded with its source position and reported, all at once, when the App starts. The diagram shows it too.

func NewService 

func NewService(name, doc string) *Service

NewService declares a service. name must be lower-case letters, digits and dashes, starting with a letter; doc is one sentence saying what it owns.

func (*Service) Activity 

func (s *Service) Activity(fn func(context.Context) bool) *ActivityHandler

Activity declares that the service is busy while fn returns true: a daemon whose clients are sessions, not connections, stops once the last session ended rather than once the last connection closed. fn is called on the idle watch's tick, from one goroutine, and must answer quickly; a panic counts as busy, and is logged. The value is kept for the declaration: 

var _ = Service.Activity(func(context.Context) bool { return sessions.Open() > 0 })

func (*Service) AuthHandler 

func (s *Service) AuthHandler[P, D any](name string, handler func(context.Context, P) (UID, D, error)) *AuthenticatorHandler[P, D]

AuthHandler declares the app's authentication handler. The handler returns the user's ID and data; an empty UID with a nil error means "no credentials", which Auth endpoints answer 401 and AuthOptional endpoints serve anonymously; an error — usually Unauthenticated — refuses the request.

The handler runs only for a request that carries at least one of the credentials' cookies or headers; a request with none is anonymous without asking it.

func (*Service) CLI 

func (s *Service) CLI(name, doc string, fn CLIFunc, opts ...CommandLineConfigurer) *CLI

CLI declares a command named name, which Main runs when the process is called "<binary> <name> ...". doc is its one-line help.

func (*Service) Command 

func (s *Service) Command[C, R any](name string, handler func(context.Context, C) (R, error), opts ...CommandConfigurer) *Command[C, R]

Command declares a command of the service: an operation named name, run by handler, that changes something. Its node is "<service>/command/<name>". 

var PlaceOrder = Service.Command("place-order", placeOrder).
	Allow(Policy, "place", "order").
	Expose("POST /orders")

func (*Service) Cron 

func (s *Service) Cron(name, expr string, fn func(context.Context) error) *Job

Cron declares a job that runs on a five-field POSIX cron expression, in the process's local time zone.

func (*Service) Endpoint 

func (s *Service) Endpoint[Req, Resp any](route string, handler func(context.Context, Req) (Resp, error), opts ...EndpointConfigurer) *EndpointService[Req, Resp]

Endpoint declares an HTTP endpoint on route — "METHOD /path/{param}" — run by handler. The request is decoded from the path, the query, the headers (fields tagged `path:"…"`, `query:"…"`, `header:"…"`) and the JSON body (every other field), then checked against its `validate` tags, then handed to the policies (RateLimit, Timeout, Bulkhead) and the handler. The response is JSON, or 204 No Content when it is EmptyValue.

An endpoint is for what HTTP itself is about — a webhook a third party calls. A business operation is a command or a query, exposed on its route (Command.Expose, Query.Expose), and run in process by the code that needs it (Command.Dispatch, Query.Ask).

The endpoint's name, and so its node ID, is the handler's function name.

func (*Service) Every 

func (s *Service) Every(name string, period time.Duration, fn func(context.Context) error) *Job

Every declares a job that runs every period, first one period after the app starts.

func (*Service) Go 

func (s *Service) Go(name string, run func(context.Context) error) *Routine

Go declares a hand-written loop. run must return when ctx ends; returning earlier, with or without an error, restarts it after a backoff.

Everything run does is drawn from the loop's node: a store it reads, a topic it publishes on. kit has no span around it — a run lasts as long as the app — so each of those calls starts a trace of its own.

func (*Service) Implement 

func (s *Service) Implement[Req, Resp any](port *PortService[Req, Resp], handler func(context.Context, Req) (Resp, error), opts ...EndpointConfigurer) *EndpointService[Req, Resp]

Implement declares that the service implements port: an endpoint of the service with no route, which only the port reaches, in process, when the app binds nothing else and this is the one implementation among the services it mounts. It runs as every endpoint does — the request's validate tags, the options' policies, the caller's user — and is named like one: its Name, else its handler's name, else, for a function literal, the port's name. A handler whose request or response is not the port's does not compile. A host implements a module's port on its own service: it never adds a node to the module's. 

var _ = posts.Service.Implement(desk.Enforcer, Enforce)

func (*Service) Listen 

func (s *Service) Listen(name, contract string, handler ListenHandler, opts ...ListenerConfigurer) *Listener

Listen declares a listener named name speaking contract — "<name>/v<major>", "render/v1" — whose connections handler serves, one goroutine each.

func (*Service) Loop 

func (s *Service) Loop(name string, run func(context.Context, WakeEvent) error, opts ...LoopConfigurer) *Loop

Loop declares a loop run by kit: run is called once at start, then on every wake.

Runs never overlap: wakes that come while the function runs are gathered into one run after it. A run that fails or panics is counted, and the next one waits a backoff — one second, doubling up to a minute — unless it is a Loop.Nudge. A deadline already past wakes the loop at once, but never sooner than a second after the previous run: a WakeAt that keeps answering the past costs a run a second, not a spinning core.

func (*Service) Mailer 

func (s *Service) Mailer(name string, opts ...MailerConfigurer) *Mailer

Mailer declares outbound mail.

func (*Service) Name 

func (s *Service) Name() string

Name returns the service name, which is also its node ID: qualified with its module's, "moderation.intake", when a module lists it.

func (*Service) Port 

func (s *Service) Port[Req, Resp any](name string, opts ...PortConfigurer[Req, Resp]) *PortService[Req, Resp]

Port declares a port of the service: an operation it needs, named name, taking Req and answering Resp, which another service implements (Service.Implement) or the app binds (Bind). Its node is "<service>/port/<name>"; its doc is its declaration's doc comment.

func (*Service) Query 

func (s *Service) Query[Q, R any](name string, handler func(context.Context, Q) (R, error), opts ...QueryConfigurer) *Query[Q, R]

Query declares a query of the service: an operation named name, run by handler, that reads and changes nothing. Its node is "<service>/query/<name>". 

var MyOrders = Service.Query("my-orders", myOrders, kit.Auth()).Expose("GET /orders", kit.AnyUser())

func (*Service) Secret 

func (s *Service) Secret(name string, opts ...SecretConfigurer) *Secret

Secret declares a secret the product needs.

Without an option it is provided: the operator gives it in the environment — the variable <APP>_<NAME>, TODO_STRIPE_KEY for the secret "stripe-key" of the app "todo", or TODO_STRIPE_KEY_FILE naming a file that holds it, the Docker and Kubernetes way — or in the environment's store, with `kit secrets set`. It is read at every use, so replacing it where it lives takes effect without a restart, and a start without it fails, naming the variable to set.

With Optional, a start without it goes on: the product asks Secret.Present before it uses the secret.

With Generated, kit makes it: version 1 on the first start, a new version on its schedule, the previous ones kept so that what they sealed or signed still opens and verifies. It lives in the store the environment keeps — an encrypted file store in dev, KIT_SECRETS elsewhere. Its variable pins it: kit then uses the value as it is and does not rotate it.

name is 1 to 63 lower-case letters, digits and dashes, starting and ending with a letter or a digit — one grammar for a file name and a variable — and unique in the app.

func (*Service) Setting 

func (s *Service) Setting[T SettingValue](name string, def T, opts ...SettingConfigurer) *SettingService[T]

Setting declares a setting of the service: name holds def unless the environment says otherwise — the variable <APP>_<NAME>, TODO_BASE_URL for the setting "base-url" of the app "todo", or the key name in the product's configuration files. SettingService.Get reads it.

name follows the secrets' grammar — 1 to 63 lower-case letters, digits and dashes, starting and ending with a letter or a digit — and is unique in the app, among its settings and its secrets: the two share their variables.

func (*Service) Static 

func (s *Service) Static(name, prefix string, fsys fs.FS, opts ...StaticConfigurer) *Frontend

Static declares a frontend serving fsys under prefix, which must end with '/'. A path with no file extension that matches no file serves index.html, so client-side routing works; a missing file with an extension — a script, a stylesheet — stays a 404. A directory is never listed. The SDK's static handler serves it; kit draws it and observes every request.

func (*Service) Store 

func (s *Service) Store[T any](name string, key func(T) string, opts ...StoreConfigurer) *StoreService[T]

Store declares a store of entities of type T, keyed by key.

func (*Service) Subscribe 

func (s *Service) Subscribe[T any](name string, topic *TopicService[T], handler func(context.Context, T) error, opts ...SubscriptionConfigurer) *SubscriptionWorker[T]

Subscribe declares a subscription of the service to topic. Delivery is at least once: handler must be idempotent, which is the one thing the SDK's queue cannot check and kit therefore asks you to promise here.

func (*Service) Topic 

func (s *Service) Topic[T any](name string) *TopicService[T]

Topic declares a topic carrying messages of type T.

func (*Service) Watch 

func (s *Service) Watch(name string, mark Mark, handler func(context.Context, WrittenEvent) error, opts ...SubscriptionConfigurer) *Watch

Watch declares a watch of the service: handler is told of every write kit confirms on a store whose entity holds a field that carries mark — the product's stores and the other modules', never those of the module the service belongs to (for a service of the product's, never the product's own) unless OwnStores says so. The notice says which store, which record and whether it was deleted; the handler reads the record itself (RecordsOf). Delivery is at least once and in no set order, retried and dead-lettered after MaxDeliveries attempts: handler must be idempotent, and it hears the writes it makes itself on another's store — with OwnStores, never a write its own handler makes. After a stop that was not clean — the process died with the watch running —, its next start queues a notice for every record of every store that feeds it, so that no write a crash took the notice of goes unheard; a deletion whose notice was lost is not among them. The mark that says a watch runs is kept in the data directory: an app without one does not catch up (ADR 0178 C6). 

var Content = Service.Watch("content", kit.Moderated, Screen)
var Posts = Service.Watch("posts", kit.Moderated, Stamp, kit.OwnStores())

func (*Service) Workflow 

func (s *Service) Workflow[E any, S comparable](name string, store *StoreService[E], state func(*E) *S) *WorkflowService[E, S]

Workflow declares a state machine over the entities of store. state returns a pointer to the entity's state field.

type SettingConfigurer 

type SettingConfigurer interface {
	// contains filtered or unexported methods
}

SettingConfigurer configures a setting.

func Required 

func Required() SettingConfigurer

Required drops a setting's default: a start without a value for it fails, saying where to give one.

IFACE-OPAQUE: the option is sealed — its method is unexported — so a caller only hands it to the declaration it configures.

type SettingService 

type SettingService[T SettingValue] struct {
	// contains filtered or unexported fields
}

SettingService is a value the environment gives a service, declared with Service.Setting.

func NewSettingService 

func NewSettingService[T SettingValue](def T) *SettingService[T]

NewSettingService is a setting no service declares yet, holding def until something sets it: Service.Setting makes one and declares it, which is how a product gets one.

func (*SettingService[T]) Get 

func (s *SettingService[T]) Get() T

Get returns the setting's value in the app the service is mounted in — its default until an app has started with it.

func (*SettingService[T]) Name 

func (s *SettingService[T]) Name() string

Name is the setting's name, its key in a configuration file — in its module's section, for a module's setting.

type SettingValue 

type SettingValue interface {
	string | bool | int | int64 | float64 | time.Duration | []string
}

SettingValue is what a setting may hold.

type StaticConfigurer 

type StaticConfigurer interface {
	// contains filtered or unexported methods
}

StaticConfigurer configures a frontend.

func Root 

func Root(dir string) StaticConfigurer

Root serves the sub-directory dir of the file system rather than its root — "assets" for a //go:embed assets directive.

IFACE-OPAQUE: the option is sealed — its method is unexported — so a caller only hands it to the declaration it configures.

type StdioValue 

type StdioValue struct {
	// In is the command's standard input.
	In io.Reader
	// Out and Err are its standard output and error.
	Out, Err io.Writer
	// Interactive reports whether In is a terminal.
	Interactive bool
}

StdioValue is where a CLI command reads and writes: the process's own streams under Main, buffers in a test.

type StoreConfigurer 

type StoreConfigurer interface {
	// contains filtered or unexported methods
}

StoreConfigurer configures a store.

func Anonymise 

func Anonymise[T any](fn func(*T)) StoreConfigurer

Anonymise says what an erased record keeps: fn runs first, and generalises into unclassified fields — a birth date to its year, an address to its region; then kit clears the rest. kit cannot prove that what remains identifies no one: by declaring the function, the product asserts it.

func DeleteAfter 

func DeleteAfter[T any, D Delay](delay D, since func(T) (time.Time, bool)) StoreConfigurer

DeleteAfter deletes a record delay after the instant since returns.

func DeleteAt 

func DeleteAt[T any](at func(T) (time.Time, bool)) StoreConfigurer

DeleteAt deletes a record at the instant at returns.

func DeleteOnErasure 

func DeleteOnErasure() StoreConfigurer

DeleteOnErasure makes a person's erasure (kit.Erase) delete the store's records instead of clearing them, as sessions and accounts want.

func EraseAfter 

func EraseAfter[T any, D Delay](delay D, since func(T) (time.Time, bool)) StoreConfigurer

EraseAfter erases a record's personal data delay after the instant since returns — its closing, say; false means "not yet": an open record is never due. delay is a duration, or a duration setting.

func EraseAt 

func EraseAt[T any](at func(T) (time.Time, bool)) StoreConfigurer

EraseAt erases a record's personal data at the instant at returns: one the product computed and stored on the record — a retention in calendar months, one that depends on a tenant.

func HeldUntil 

func HeldUntil[T any](until func(T) (time.Time, bool), reason string) StoreConfigurer

HeldUntil holds each record until the instant until returns: the law's own retention, such as an invoice kept ten years (GDPR art. 17(3)(b)). reason is the legal ground, for the register. A held record is exported and updated like any other, and neither erased nor deleted.

func Index 

func Index[T any](name string, keys func(T) []string) StoreConfigurer

Index declares an index where an entity may have several keys and a key several entities — the users a task is shared with. StoreService.Find reads it. Empty keys are not indexed.

func Purpose 

func Purpose(text string) StoreConfigurer

Purpose says why the store keeps its records (GDPR art. 30(1)(b)): the register lists it, and a person's export carries it.

func ReadModel 

func ReadModel() StoreConfigurer

ReadModel marks a store as derived from others (ADR 0005): written by projections — the subscriptions that keep it from the write side's events —, read by queries. It changes nothing of how the store runs; the diagram draws it on its domain's read side, and the static analysis warns of a read model written by anything but a subscription. kit's topics are queues, not logs: a read model cannot be replayed from its events, and one fed by a topic lags the commands that feed it — a query that must read its own writes reads the write side. 

var Summaries = Service.Store("summaries", Summary.Key, kit.ReadModel())

func RetentionByProduct 

func RetentionByProduct(limits string) StoreConfigurer

RetentionByProduct says the product keeps the store's retention itself: its own code erases and deletes what it no longer needs — a record whose life the product's own rules end, a lifecycle kit cannot read from the entity. limits says, in the product's words, for how long and how, which the register publishes as the store's time limits (GDPR art. 30(1)(f)); "" says only that the product keeps them.

kit then runs no retention for the store, and warns of neither a missing retention nor a missing subject. Its classified fields keep every other promise: sealed at rest, never shown, exported with their person — when the store names one — and erased by kit.Erase and Store.Erase. It goes with kit.Purpose, kit.HeldUntil, kit.Anonymise and kit.DeleteOnErasure; with kit.EraseAfter, kit.EraseAt, kit.DeleteAfter or kit.DeleteAt it is refused: a store's retention is kit's or the product's, never both.

func Revisions 

func Revisions(n int) StoreConfigurer

Revisions keeps the n previous versions of each record of the store, n from 1 to 100, as WordPress keeps a post's revisions: every write that changes a record makes a version, numbered from 1 and never renumbered, stamped with when it was made, the caller's user and the command that made it; the oldest beyond n are pruned by the write that makes a newer one, unless a legal hold keeps the record. 

var Pages = Service.Store("pages", Page.Key, kit.Revisions(20))

revs, err := Pages.Revisions(ctx, id)                            // newest first
edits, err := Pages.Diff(ctx, id, revs[3].Number, revs[0].Number)
page, err := Pages.Restore(ctx, id, revs[3].Number)              // a new version
page, err = Pages.Restore(ctx, id, revs[3].Number, "/title")     // the title only

A store with Revisions(n) holds up to n+1 times its records: in memory with the store in the data directory, in the table <table>___vs on a database, which kit's migrations create.

func Unique 

func Unique[T any](name string, key func(T) string) StoreConfigurer

Unique declares a unique index: no two entities may share a key, and a write that would is refused with a Conflict error. An empty key is not indexed. StoreService.Lookup reads it. 

var Accounts = Service.Store("accounts", Account.Key,
	kit.Unique("email", func(a Account) string { return a.Email }))

type StoreService 

type StoreService[T any] struct {
	// contains filtered or unexported fields
}

StoreService is a typed, keyed collection of entities. Every read returns a copy and every write stores one: an entity is kept as its JSON encoding, so what a handler holds can never alias what the store holds, and the memory and file backends behave identically.

With a data directory (KIT_DATA_DIR; ".kit/data" in dev) the store persists every write before returning, atomically — a crash never leaves a torn file — and a write costs one entity, whatever the store holds. Without one, it lives in memory. A store a database keeps (Database, Keeps) lives in a table of it, and every call is a round trip. A store is a port (ADR 0004): what it runs on is its engine (store_engine.go) — the SDK's document store, in memory, in files or over SQL —; kit makes it a node of the graph, observes every call, and speaks for its refusals. Its writes join the transaction their context carries (Transact).

func NewStoreService 

func NewStoreService[T any](key func(T) string) *StoreService[T]

NewStoreService is a store no service declares yet, keying its entities with key: Service.Store makes one and declares it, which is how a product gets one.

func (*StoreService[T]) Count 

func (s *StoreService[T]) Count(ctx context.Context) (int, error)

Count returns how many entities the store holds.

func (*StoreService[T]) Delete 

func (s *StoreService[T]) Delete(ctx context.Context, key string) error

Delete removes the entity with the given key, or returns a NotFound error. When the store seals at rest and the entity was its person's last record, their data key goes with it, as with an erasure — at the commit, in a Transact —, once nothing kit keeps still needs it: a held record, or a former value or version sealed under it, keeps the key.

func (*StoreService[T]) Diff 

func (s *StoreService[T]) Diff(ctx context.Context, key string, from, to uint64) ([]Edit, error)

Diff returns what changed from the version numbered from to the version numbered to of the record under key, in RFC 6902's words — add, remove, replace, each at a JSON pointer — with both values, in the order they apply: none when the two are the same. A secret member says it changed, never what. Showing a text's changes line by line is the reader's: the Studio does it.

func (*StoreService[T]) Erase 

func (s *StoreService[T]) Erase(ctx context.Context, key, reason string) error

Erase erases one record now, as its retention would: its personal, special and secret members and its subject cleared — after the store's Anonymise function has kept what it generalises —, its erased fields stamped, the rest kept. A held record is refused with a Conflict that names the hold, never a placed hold's reason. reason is journaled, for whoever runs the product.

func (*StoreService[T]) Filter 

func (s *StoreService[T]) Filter(ctx context.Context, keep func(T) bool) ([]T, error)

Filter returns the entities keep accepts, ordered by key. It reads every entity: an index is the way to avoid it.

func (*StoreService[T]) Find 

func (s *StoreService[T]) Find(ctx context.Context, index, key string) ([]T, error)

Find returns the entities indexed under key, ordered by their store key. It reads any index, unique or not; no entity is an empty slice, not an error.

func (*StoreService[T]) Former 

func (s *StoreService[T]) Former(ctx context.Context, key, pointer string) ([]Former, error)

Former returns the former values of the field at pointer — its JSON pointer (RFC 6901), "/email" — in the record under key, newest first: each with when it was replaced and by whom. A secret field's former values say when they changed, never what they were: their Value is empty. A field that keeps no former values is an Invalid error, a missing record a NotFound.

func (*StoreService[T]) Get 

func (s *StoreService[T]) Get(ctx context.Context, key string) (T, error)

Get returns the entity with the given key, or a NotFound error.

func (*StoreService[T]) Hold 

func (s *StoreService[T]) Hold(ctx context.Context, key, reason string) error

Hold places a legal hold on the record under key: neither the retention, nor a person's erasure, nor Delete touches it until StoreService.Release lifts it. reason says why — an authority's request, a case under litigation — and is kept for whoever runs the product, never shown in the Studio. Holding a held record again replaces its reason.

func (*StoreService) ID 

func (n *StoreService) ID() string

ID returns the node's identifier in the product graph: "<service>/<kind>/<name>".

func (*StoreService[T]) Insert 

func (s *StoreService[T]) Insert(ctx context.Context, v T) error

Insert stores a new entity; it is a Conflict error when the key exists.

func (*StoreService[T]) List 

func (s *StoreService[T]) List(ctx context.Context) ([]T, error)

List returns every entity, ordered by key.

func (*StoreService[T]) Lookup 

func (s *StoreService[T]) Lookup(ctx context.Context, index, key string) (T, error)

Lookup returns the entity whose key in the unique index is key, or a NotFound error. Asking a non-unique index is an Invalid error: use StoreService.Find.

func (*StoreService[T]) Passwords 

func (s *StoreService[T]) Passwords(field func(*T) *string, opts ...PasswordConfigurer) *PasswordPolicyService[T]

Passwords declares the password policy of one secret field of the store's entity; field names it — kit calls it on a zero entity to find which. The field then only ever holds the password's hash, a PHC string, or nothing before a first password; a write that puts anything else in it is refused. A field that is not secret refuses the start, as does a second policy on the same field.

func (*StoreService[T]) Put 

func (s *StoreService[T]) Put(ctx context.Context, v T) error

Put stores the entity, replacing any entity with the same key.

func (*StoreService[T]) Release 

func (s *StoreService[T]) Release(ctx context.Context, key string) error

Release lifts the hold on the record under key: the retention takes it up again, from where its instants say. A record no hold keeps is a NotFound error.

func (*StoreService[T]) Restore 

func (s *StoreService[T]) Restore(ctx context.Context, key string, number uint64, fields ...string) (T, error)

Restore writes the version numbered number of the record under key back, as a new version: history is never rewritten. It restores the whole version, or only the fields named by JSON pointer (RFC 6901) — "/title" —, as WordPress restores some fields of a revision. It keeps the record's workflow state, which its workflow owns, and every secret member: restoring an account never brings back an old password past its policy, and naming one of them is an Invalid error. A unique index the restored record breaks refuses it with a Conflict, and nothing changes. It returns the record as restored.

func (*StoreService[T]) Revision 

func (s *StoreService[T]) Revision(ctx context.Context, key string, number uint64) (RevisionEvent[T], error)

Revision returns the version numbered number of the record under key, its secret members zeroed: a NotFound when the record keeps none of that number — never made, or pruned.

func (*StoreService[T]) Revisions 

func (s *StoreService[T]) Revisions(ctx context.Context, key string) ([]RevisionEvent[T], error)

Revisions returns the versions the store keeps of the record under key, newest first: the record as it is now, then the former ones — n at most, more while a legal hold keeps the record. A secret member is zeroed in each: a former password hash never reaches the product. A missing record is a NotFound, a store that keeps no revisions an Invalid.

func (*StoreService[T]) Update 

func (s *StoreService[T]) Update(ctx context.Context, key string, fn func(*T) error) (T, error)

Update applies fn to the entity with the given key and stores the result, atomically with respect to every other write of this store. fn must not change the key. An error from fn leaves the entity untouched.

fn runs while the store's writers wait — on a database, inside the write's transaction, the entity locked —: it may read this store, but must not write to it, nor fire a workflow over it — either would wait for the write fn is part of.

type SubscriptionConfigurer 

type SubscriptionConfigurer interface {
	// contains filtered or unexported methods
}

SubscriptionConfigurer configures a subscription.

func OwnStores 

func OwnStores() SubscriptionConfigurer

OwnStores lets a watch (Service.Watch) hear the stores of its own module too — the product's own, for a watch of the product's —, which a watch never hears by default. Such a watch never hears the writes its own handler makes, in its handler's context — a handler that writes what it watches, a screening that stamps the record it screened, would otherwise hear itself forever —; a write the handler only causes, later and elsewhere — a queued command's handling, a topic's delivery — is heard. A subscription to a topic refuses it: a topic has no stores.

type SubscriptionWorker 

type SubscriptionWorker[T any] struct {
	// contains filtered or unexported fields
}

SubscriptionWorker consumes a topic: its handler runs once per message, at least once, retried on error, and dead-lettered after MaxDeliveries attempts.

func (*SubscriptionWorker) ID 

func (n *SubscriptionWorker) ID() string

ID returns the node's identifier in the product graph: "<service>/<kind>/<name>".

type TopicService 

type TopicService[T any] struct {
	// contains filtered or unexported fields
}

TopicService is an asynchronous channel of messages of type T. Every subscription receives every message, at least once: a subscription's handler must tolerate a redelivery.

func NewTopicService 

func NewTopicService[T any]() *TopicService[T]

NewTopicService is a topic no service declares yet: Service.Topic makes one and declares it, which is how a product gets one.

func (*TopicService) ID 

func (n *TopicService) ID() string

ID returns the node's identifier in the product graph: "<service>/<kind>/<name>".

func (*TopicService[T]) Publish 

func (t *TopicService[T]) Publish(ctx context.Context, msg T) error

Publish sends msg to every subscription. It returns once every subscription's queue has accepted the message; delivery happens later. Inside a transaction (Transact, a command's) the message is encoded now and queued at the commit: in the transaction, just before it commits, for a subscription whose queue lives on the transaction's database — a queue that refuses it then fails the transaction —, once it committed for the others. A rollback drops it.

type UID 

type UID string

UID identifies an authenticated user. It is what the auth handler returns and what every endpoint reads with UserID.

func UserID 

func UserID(ctx context.Context) (UID, bool)

UserID returns the authenticated caller of the request ctx serves, and whether there is one. An in-process EndpointService.Call carries its caller's user along.

type ViolationMessage 

type ViolationMessage struct {
	// Path locates the value: "title", "items[2].zip".
	Path string `json:"path"`
	// Rule names the failed rule: "required", "maxlen".
	Rule string `json:"rule"`
	// Message explains it without echoing the value.
	Message string `json:"message"`
}

ViolationMessage is one validation rule a request failed: where, which rule, and why — never the value.

type WakeEvent 

type WakeEvent struct {
	// Reason is model.WakeInterval, WakeDeadline, WakeTopic, WakeStart or
	// WakeManual: WakeManual when a nudge is among the wakes the run
	// gathers — the one wake that cuts a backoff short —, else the first
	// that came.
	Reason string
	// At is when the wake happened, on the app's clock.
	At time.Time
	// Topic is the topic node whose publish woke the loop first, when a
	// topic's did.
	Topic string
	// Reasons are the reasons of every wake the run gathers, each once, in
	// the order they came: Reason is among them.
	Reasons []string
	// Topics are the topic nodes whose publish woke the loop into this run,
	// each once, in the order they came: Topic is the first.
	Topics []string
}

WakeEvent says why a declared loop runs: the reason, the instant, and the topic that woke it when one did. Wakes that come while it runs, or while it backs off after a failure, are gathered into one run: Reasons and Topics say every one of them, and Reason the one that decides the run.

type Watch 

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

Watch is a subscription fed by stores instead of a topic: its handler is told of every write kit confirms on a store whose entity holds a field with its mark. Service.Watch declares one.

func (*Watch) ID 

func (n *Watch) ID() string

ID returns the node's identifier in the product graph: "<service>/<kind>/<name>".

type WorkflowService 

type WorkflowService[E any, S comparable] struct {
	// contains filtered or unexported fields
}

WorkflowService is a state machine over the entities of one store: the states an entity goes through, and the arrows between them. It is declared as data — which is why the diagram can draw it exactly — and it runs four kinds of transitions:

The SDK's state-machine engine runs it (statemachine). Its loop never polls: it keeps an agenda of the transitions due, sleeps until the earliest, and a write of the store — which may bring one forward — wakes it. A workflow with nothing due does not run at all. Transitions of one entity run one at a time, of different entities at once.

The entity's state lives in the entity itself (the state function returns a pointer to it), so the store stays the single source of truth; the engine keeps, beside it, when each entity entered its state and the history of its transitions — in the workflow's file under the data directory, so a timer keeps counting across a restart.

func NewWorkflowService 

func NewWorkflowService[E any, S comparable](store *StoreService[E], state func(*E) *S) *WorkflowService[E, S]

NewWorkflowService is a workflow no service declares yet, over the entities of store whose state state reads: Service.Workflow makes one and declares it, which is how a product gets one.

func (*WorkflowService[E, S]) After 

func (w *WorkflowService[E, S]) After[D Delay](event string, d D, from, to S) *WorkflowService[E, S]

After declares a timer transition: an entity that has spent d in state from moves to state to, fired by the workflow's own loop. d is a duration, or a setting of the service that holds one — which must then be positive.

func (*WorkflowService[E, S]) At 

func (w *WorkflowService[E, S]) At(event string, from, to S, instant func(E) (time.Time, bool)) *WorkflowService[E, S]

At declares a timer transition at an instant the entity carries — a due date, a deadline: an entity in state from moves to state to once the time instant returns has come; false means no instant for now. kit asks again each time the entity is written, and the workflow's own loop sleeps until the earliest instant.

func (*WorkflowService[E, S]) Can 

func (w *WorkflowService[E, S]) Can(e E, event string) bool

Can reports whether event may be fired on e.

func (*WorkflowService[E, S]) Census 

func (w *WorkflowService[E, S]) Census(ctx context.Context) (map[S]int, error)

Census counts the entities per state; every declared state is present. The engine keeps the count; the call is drawn, as the diagram declares it, as a read of the store.

func (*WorkflowService[E, S]) Fire 

func (w *WorkflowService[E, S]) Fire(ctx context.Context, key, event string) (E, error)

Fire moves the entity with the given key along the event transition leaving its current state. It is a Conflict error when no such transition exists, and a NotFound error when the entity does not.

func (*WorkflowService) ID 

func (n *WorkflowService) ID() string

ID returns the node's identifier in the product graph: "<service>/<kind>/<name>".

func (*WorkflowService[E, S]) Initial 

func (w *WorkflowService[E, S]) Initial(state S) *WorkflowService[E, S]

Initial sets the state a new entity enters with WorkflowService.Start.

func (*WorkflowService[E, S]) On 

func (w *WorkflowService[E, S]) On(event string, from, to S) *WorkflowService[E, S]

On declares an event transition: WorkflowService.Fire with this event moves an entity in state from to state to. One event may leave several states, but only one arrow per (event, from).

func (*WorkflowService[E, S]) OnEnter 

func (w *WorkflowService[E, S]) OnEnter(state S, fn func(context.Context, *E) error) *WorkflowService[E, S]

OnEnter runs fn when an entity enters state, before it is stored. An error cancels the transition, and so does a panic — reported as CodeWorkflowHookPanic, the entity free for the next transition. fn may change the entity, not its state nor its key (CodeWorkflowHookChange), and must not fire this workflow, which is refused (CodeWorkflowReentrant): transitions of one entity run one at a time.

func (*WorkflowService[E, S]) OnTransition 

func (w *WorkflowService[E, S]) OnTransition(fn func(context.Context, ChangeEvent[E, S]) error) *WorkflowService[E, S]

OnTransition runs fn after every transition has been stored, whoever fired it — the natural place to publish it on a topic. An error or a panic is logged and shown by the Studio; the transition stands, and the next hooks still run.

func (*WorkflowService[E, S]) Start 

func (w *WorkflowService[E, S]) Start(ctx context.Context, e E) (E, error)

Start enters a new entity into the workflow: it sets the initial state, runs the OnEnter hooks, and inserts the entity in the store.

func (*WorkflowService[E, S]) When 

func (w *WorkflowService[E, S]) When(event string, from, to S, guard func(E) bool) *WorkflowService[E, S]

When declares a guard transition: an entity in state from moves to state to as soon as guard holds. The guard sees the entity only: kit checks it each time the entity is written, never on a clock — a condition that depends on the time is an instant, declared with WorkflowService.At.

type WrittenEvent 

type WrittenEvent struct {
	// Store is the store's node ID: "shop/store/reviews".
	Store string `json:"store"`
	// Key is the record's key in the store.
	Key string `json:"key"`
	// Deleted is set when the write deleted the record: there is nothing
	// left to read.
	Deleted bool `json:"deleted,omitempty"`
	// Fields are the store's fields that carry the watch's mark, as
	// [App.Fields] lists them. Which of them the write changed, the notice
	// does not say.
	Fields []FieldRefValue `json:"fields,omitempty"`
}

WrittenEvent is what a watch is told of a write: which store, which record, and whether it was deleted — never a value. The watch reads the record itself (RecordsOf): without its secret members, and journaled.

Source Files

View all Source files

Directories

Path Synopsis
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).
 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).
Package serverkit is what framework/kit/server plugs into kit: the HTTP engine an app in the server profile serves on (the SDK's net/server), the frontends' file server (the SDK's net/static), and the process sampler of the runtime graph a serving app answers (the SDK's proc/process, and through it runtime/metrics and the spawn engine).
 Package serverkit is what framework/kit/server plugs into kit: the HTTP engine an app in the server profile serves on (the SDK's net/server), the frontends' file server (the SDK's net/static), and the process sampler of the runtime graph a serving app answers (the SDK's proc/process, and through it runtime/metrics and the spawn engine).
Package studiokit — the Studio's live events, as a Server-Sent Events stream.
 Package studiokit — the Studio's live events, as a Server-Sent Events stream.

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.