sdk

module
v0.59.0 Latest Latest
Warning

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

 Go to latest Published: Nov 3, 2026 License: MIT

README

kitsunium/sdk

A Go SDK providing a normed, performant toolbox for downstream applications: structured logging, universal codec dispatch, typed errors with stable wire codes, a crypto suite, and OS process supervision.

Packages

pkg/v1 ships 87 packages: 4 at the top level — errs, clock, crypto and proc — plus eighty-three nested ones (the six scheme facades under crypto/ — agree, hash, kdf, mac, password, sign — the six under concur/ — group, singleflight, worker, batcher, snapshot, recycler — the two under collections/ — heap, ring — the five under security/ — authz, redact, secret, session, token — the six under net/ — server, client, tlsid, sse, websocket, static — the six under observe/ — logger, logger/writer, logger/slogbridge, metrics, trace, profiling — the nine under proc/ — process, signal, reaper, rlimit, cgroup, memlimit, ipc, systemd/notify, systemd/listen — the twenty-eight under data/ — codec, its sixteen per-format packages (codec/asn1, codec/baseenc, codec/bson, codec/cbor, codec/csv, codec/flatbuffers, codec/form, codec/json, codec/msgpack, codec/multipart, codec/ndjson, codec/pem, codec/tlv, codec/toml, codec/xml, codec/yaml), codec/strictjson, codec/strictjson/httpbody, codec/jsonshape, codec/jsonpatch, transform, sql, docstore, queue, cache, vfs, semver — and the fifteen under app/ — config, cli, i18n, validation, view, events, scheduler, statemachine, resilience, lifecycle, health, lock, id, mail, mail/spool), and links the standard library and nothing else (ADR 0156). They are grouped below by the job they do, and each links to its own generated README.md. The distribution mechanisms that close the list are the framework's packages, imported from github.com/kitsunium/sdk/framework/… (ADR 0158).

Observability
Package What it does
logger + writer, slogbridge Structured logger, one allocation per emit (see its BENCH.md). Multi-sink (console / file / syslog / memory), middleware chain, build-time version stamping; writer is the named, config-driven sink registry and slogbridge is the one package allowed to import log/slog, so a consumer facing a concrete *slog.Logger stops building a second pipeline. Trace-correlated by default: a record emitted inside a span carries trace_id / span_id as top-level fields; one emitted outside carries neither key rather than an invalid all-zero id. LevelGate gives one branch of a fan-out a floor of its own — a terminal at Info, a viewer at Debug.
metrics The OpenTelemetry metrics data model, implemented from the specification with zero go.opentelemetry.io imports. Typed attributes whose kind is part of the series identity, explicit delta/cumulative temporality, OTLP/JSON on the wire. The Prometheus exporter is a deliberately lossy connector and says which losses it takes.
trace Distributed tracing on the OTel trace model + W3C Trace Context, both written from their documents. The sampling decision is taken once at the root and travels in the sampled bit, so a trace never has holes. A malformed traceparent starts a new trace and never fails a request.
health Liveness, readiness and startup are three questions, so they take three types: a readiness Check gets a context and may reach a dependency; a liveness SelfCheck has none to reach one with. The classic mis-wiring does not compile by accident. Ask is the other end — the question a container's HEALTHCHECK asks, from a binary in an image with no shell and no curl: ready means 200 and nothing else, and every other outcome has its own code.
profiling The process's own CPU, heap and goroutines. A CPU window and the live heap captured through runtime/pprof — one CPU profiler per process, so a second capture is refused rather than queued — the pprof format decoded with the standard library, samples folded onto owners you name so the parts add up to the total exactly, and the runtime's goroutine dump read into goroutines and grouped. A heap profile is sampled, and the doc says so first.
Application plumbing
Package What it does
config env + file layering, typed decode, cross-OS poll-watch, and a schema: a missing required key fails at startup with every missing key named at once, an unknown key is refused by default, and a default is a layer under every source so timeout = 0 stays 0.
lifecycle Ordered bring-up, reverse teardown. A partial start is unwound before Start returns, through the same path an ordinary Stop uses; the shutdown budget is per component, so the first thing that will not finish cannot spend everyone else's. A supervisor keeps a component's loop running: restarted after an error, an early return or a panic, on a growing backoff, and joined on stop.
cli Sub-commands, generated help and a typed exit status on the stdlib flag, with zero dependencies. flag.ExitOnError is refused by name — nothing here can end your process.
events In-process synchronous bus keyed on the event's concrete Go type. Not a queue: no durability, no retry, no dead-letter path, and deliberately no async mode.
queue The asynchronous, durable counterpart. At-least-once, and the consequence is in the type: Deliveries counts from 1 and HandlerIsIdempotent is refused at its zero value. The durable broker's whole state is a directory and every transition is one rename(2). An idle consumer sleeps until a publication, a retry falling due or a lapsed lease wakes it, so the poll only bounds what another process publishes.
scheduler Five-field POSIX cron + fixed intervals. DST, missed deadlines and overlap are decided and documented rather than emergent.
statemachine Entities of your store moved along declared states: events you fire, timers after a duration in a state, deadlines the entity carries, guards on it. One transition per entity at a time, a hook that panics never leaves one locked, and a replace never resurrects a deleted entity. The loop keeps an agenda — one heap entry per entity — so it sleeps until the next transition due or a write and finds it in O(log N), not by re-reading the store.
cache The LRU+TTL primitive and the domain above it: invalidation by tag, stampede protection, L1/L2 chaining. Stampede protection stops at the process boundary, and says so.
clock The time port — Clock / Waiter / Timed, plus System and a ManualClock a test drives by hand. Every SDK Clock field takes one, so a timeout, a cron cadence or a lease expiry is asserted exactly, with no sleeping.
semver Version precedence the way Go writes versions — SemVer 2.0.0 with a leading v — and Go pseudo-versions recognised and read, with golang.org/x/mod's names and answers and nothing outside the standard library. An unreadable string sorts first, numbers of any size order exactly, nothing allocates.
group, singleflight, worker, batcher, snapshot, recycler (concur/) + heap, ring (collections/) The kernel's concurrency primitives and containers, published as pure aliases (ADR 0159): a fan-out that joins every failure or collects every value, one execution per key for concurrent callers, a loop ticking on an injected clock, a size-or-time batcher, a copy-on-write value, a capped object pool, a binary heap and a single-producer ring.
resilience Retry, circuit breaker, rate limit — one bucket, or one per caller with the set of callers bounded — bulkhead, timeout, fallback, hedging: composable Runner policies. The backoff curve is public and never wraps negative, and the retry waits on a clock a test can move. A policy's zero value is a safe default or an explicit refusal, never an inert policy.
lock Named exclusive leases over one process or one machine, with fencing tokens. What it does not guarantee is stated as loudly: the SDK can only issue a fence; where the resource cannot compare it, exclusion is not guaranteed against a GC pause.
id UUIDv4/v7, ULID, snowflake, NanoID, KSUID, TypeID.
Network and web
Package What it does
server + sse, websocket, static Inbound HTTP with TLS/mTLS identity, per-phase deadlines and policy; Server-Sent Events; and RFC 6455 WebSocket written in the stdlib, whose MUST-fails are enforced rather than tolerated. static serves a file tree — an embedded single-page application — the way http.FileServerFS does not: never a directory listing, never HTML for a missing script, and the security headers on every answer. Draining is announced to the handler, never imposed.
client The outbound half over the same substrate: policy, per-phase deadlines, call hooks.
tlsid TLS/mTLS identity from memory or disk, shared by both halves.
view Server-side rendering on html/template, not a reimplementation — contextual escaping is an HTML parser, and a hand-written one is where the XSS would come from. text/template has no representation at all; an AST audit fails the build on the import.
i18n Message translation with CLDR plurals over a named 13-language subset. An unsupported language is refused by name at construction, because falling back to English's two categories renders a wrong Polish sentence that nothing observes.
mail + spool MIME composition + SMTP. A CR or LF in a header is refused and never repaired, because the three stdlib helpers that would repair it deliver a message you did not write while reporting success. And a durable outbox, the spool (its own package): a mail is validated at Send and queued, retried on a growing backoff, dead-lettered with its last failure. A redelivery of a mail it delivered is dropped; the one resend left, after a crash between the relay's acceptance and the acknowledgement, carries the same Message-ID, so a receiver can recognise it.
Data and security
Package What it does
codec + one package per format, json … xml, and strictjson (+ httpbody), jsonshape, jsonpatch, json / yaml / toml / bson Universal dispatch over a Format registry — 24 formats behind one Marshal / Unmarshal / NewEncoder / NewDecoder: asn1-der, bson, cbor, csv, flatbuffers, form, json, msgpack, multipart, ndjson, pem, tlv, toml, xml, yaml + 9 base-N encodings. strictjson is the other JSON decoder, for documents somebody else wrote: one reading or a refusal — no duplicate name, no case-only match, no unknown member, no trailing data — within a byte bound, and no refusal ever quotes the input. jsonshape describes a Go type's wire shape under encoding/json — members resolved exactly as the encoder resolves them, each with the Go field behind it. jsonpatch says what changed between two JSON documents, as RFC 6902 operations with the value each writes and the value it replaces. Each per-format package — asn1, baseenc (nine base-N formats), bson, cbor, csv, flatbuffers, form, json, msgpack, multipart, ndjson, pem, tlv, toml, xml, yaml — registers its format and names its codes, so a program reading YAML links the SDK's own YAML reader and no other codec, and codec is their aggregate; bson also names BSON's value types and has its own Marshal / Unmarshal. A request body is strictjson/httpbody's, so the decoder itself links no net/http. Every codec is implemented on the standard library alone — YAML as a named subset of YAML 1.2.2 that refuses anchors, tags, merge keys and the other constructs it leaves out by name; the full yaml.v3 reader is the opt-in module third-party/codec/yaml, registered as yaml-full.
transform Compression without the codec package: gzip, raw DEFLATE and the zlib envelope from the standard library, zstd and s2 from the opt-in third-party/transform. DecompressBounded takes your ceiling and refuses a stream past it rather than cutting it short; a scheme that can be told the ceiling stops at it, so it bounds the work and not only the verdict.
errs Typed errors with dotted-quad codes (MM.LL.PP.SS) + a wire-safe Public / log-only Private split. Construction (New, Wrap, Field) and introspection (CodeOf, HasCode, NewPrefixMatcher).
crypto + hash, sign, mac, kdf, agree, password AEAD seal/open with hidden nonces, hashing, signatures, MACs, key derivation, key agreement, password hashing and a check against the ten thousand most common passwords — and JWK/JWKS, where a private export is opt-in and never the default.
token JWT over JWS Compact + PASETO v4.public. The algorithm is bound by the constructor and never read from the token, so algorithm confusion is a call that does not compile; alg:none has no representation in the type.
secret A secret is a value no rendering writes down: secret.Value prints <redacted> under every fmt verb, JSON, text and slog, reveals its bytes only through Reveal, and decodes from a configuration string like any field. Versioned stores — memory, the environment with the Docker/Kubernetes NAME_FILE convention, a 0700 directory of atomically published records sealed with AES-256-GCM — a Keyring whose boxes name the version that sealed them so a rotation never breaks what came before it, and a Rotator that keeps at least two. SubjectKeys: one data key per subject under that rotating root, so a rotation re-wraps one small key per subject and never a field, and destroying a subject's key erases every copy it sealed.
session Server-side sessions. Regenerate is the only call that binds a subject and always mints a new identifier, so session fixation is prevented by the absence of any other spelling rather than by remembering a step.
authz RBAC + ABAC with no policy DSL — a condition is a Go func. Abstention is a third verdict and the zero value, because folding "no opinion" into a grant is a hole and into a refusal is an outage.
validation Constraints, located violations (user.addresses[2].zip), collect-all by default. A message names the rule and the bound but never the value — a security property with its own test.
sql Ports above database/sql, deliberately never an ORM, and no driver. A unit of work receives an Executor with no Commit and no Rollback, so a callee ending its caller's transaction is a sentence with no spelling.
vfs Reading is io/fs unchanged (FS is a type alias, so fs.WalkDir applies with no adapter); writing is four verbs; publication is rename(2)-atomic — measured at 0 torn reads out of 600.
docstore Typed, keyed JSON documents with unique and multi-valued indexes, in memory, on a filesystem or over SQL. A write is durable before it returns and costs the same at a hundred documents or a hundred thousand: it publishes one small file, and the store rests as ONE readable snapshot. Asked to, it keeps each document's last versions in the document's own write, so no crash ever separates them.
redact Values, JSON documents, text and log attributes shown with their secrets replaced — a name that says it is one, a field declared secret, a URL's credentials — within an exact byte bound, never touching the input. What it does not recognise is stated, because it is a display filter and not an access control.
Process, platform and distribution
Package What it does
proc + process, signal, reaper, rlimit, cgroup, systemd/notify, systemd/listen OS process supervision: spawn, signals, subreaping, resource limits, cgroups, systemd readiness and socket activation. Uniform typed UnsupportedPlatform where a kernel offers no native mechanism. process also reads the process itself: its runtime state and the build it came from, a module's release, commit and local directory kept apart.
memlimit Reads the cgroup cap that already bounds this process — which the Go runtime does not — so a service in a 512 MiB container gets a soft limit instead of a SIGKILL.
ipc A private socket between processes of one machine: its directory gates it and the path above that directory is refused where another account could steer it; the kernel names the peer where it can (SO_PEERCRED on Linux; on Windows a named pipe whose own DACL names the account, each end's account read from the other's token).
git (framework) What a branch changed, as a value that can say it does not know: "nothing changed" and "I could not tell" are opposite instructions, so the resolver degrades rather than answering with an empty set. And what a working tree is at — its commit, that commit's time, whether a tracked file differs — through the same hardened invocations.
selfupdate (framework) Signature then digest then disk. Comparing an archive against a checksum file fetched beside it verifies nothing; a build with no vendor key installs nothing.
entitlement (framework) Vendor-signed roster → grant, with an offline cache, an anti-rollback ratchet and a CI seat. Bring your own Identity: three methods, and none of them says "ssh".
gate (framework) May this invocation run? A policy value and a pure decision — it verifies nothing, upgrades nothing and never ends a process.

Install

Each family of pkg/v1 is a Go module of its own — github.com/kitsunium/sdk/pkg/v1/<family> for app, clock, collections, concur, crypto, data, errs, net, observe, proc and security —, so you lock each family at its own version and a fix in one moves nothing else (ADR 0171). They are built on one shared module, …/internal, and the framework is the root module, github.com/kitsunium/sdk; none links anything but the standard library (ADR 0156):

go get github.com/kitsunium/sdk/pkg/v1/data@latest github.com/kitsunium/sdk/pkg/v1/errs@latest

then import the packages you use — github.com/kitsunium/sdk/pkg/v1/data/codec, …/pkg/v1/errs — or github.com/kitsunium/sdk@latest for …/framework/app. Importing them first and running go mod tidy works as well: Go resolves an import to the module with the longest path that provides it, which is the family's. A go.mod pinned to a root between v0.18.0 and v0.19.7, which held pkg/ and internal/, is lifted past them by the first family it adds: every family requires the root at the first version that holds neither, and the root's go.mod retracts the others, so go list -m -u says where the packages went. An integration that needs a vendor library is a module of its own, required by name, so you take that vendor and no other: go get github.com/kitsunium/sdk/third-party/aws@latest, or …/framework/connectors/postgres.

Migrating from …/pkg and …/framework (v0.17.0 and before)

Up to v0.17.0 the SDK was split into modules — …/pkg, …/framework and three …/internal/* ones your go.mod lists as // indirect. The import paths did not change, the requirement does. Since the module per family (ADR 0171), a go.mod still on …/pkg moves over by requiring the families it imports:

go get github.com/kitsunium/sdk/pkg/v1/<family>@latest   # each family you import
go mod tidy

Every family requires …/pkg at v0.18.0, its last version, which holds no package, and the three …/internal/* modules at v0.18.0, which hold none either, so minimum version selection lifts all four off the packages the family provides — without that, two modules provide them and the build fails with ambiguous import (measured on a file proxy, ADR 0171 §7). Do not add …/internal/kernel@none to that command: the families require its v0.18.0, and go get refuses the removal.

Before the split the same move went to the root module, and v0.18.0 of …/pkg and …/framework still deprecates them with that older command (go get github.com/kitsunium/sdk@v0.18.0 …/internal/kernel@none), which go get prints; it lands on a retracted root, from which adding the families is the step above. The paragraphs below describe that removal.

The one removal is enough: every version of …/pkg, …/framework, …/internal/core and …/internal/service up to v0.17.0 requires …/internal/kernel, so go get takes all five out and names each (go: removed …). Upgrading …/pkg and …/framework to v0.18.0 instead is no migration: that version is empty, and the internal modules stay. Add github.com/kitsunium/sdk/<module>@v0.18.0 to the same go get for each vendor or connector module your go.mod requires (third-party/aws, framework/connectors/postgres…); without it, go get removes that module with the old ones and go mod tidy finds it again at its newest version.

Migrate from the bottom up: a library before the modules that require it. The @none takes out, with the old modules, every module that still requires them — a library of yours still on …/pkg leaves your go.mod in the same command, and go get says so with go: removed <module> (or go: downgraded <module> when an older version of it did not use the SDK). Such a line for a module that is not the SDK's means: migrate that module first, then run the command again. When it is done,

go mod graph | grep -E 'kitsunium/sdk/(pkg|framework|internal/[a-z]+)@'

prints nothing. sdkguard prints the command when it finds a go.mod still on …/pkg, and the removal when it finds one that requires the SDK module beside an old one (ADR 0162).

Quick example

package main

import (
    "fmt"
    "github.com/kitsunium/sdk/pkg/v1/data/codec"
)

func main() {
    payload := map[string]any{"hello": "world"}
    out, err := codec.Marshal(codec.JSON, payload)
    if err != nil {
        panic(err)
    }
    fmt.Println(string(out))
}

What makes this SDK different

  • Layered architecture — kernel (stdlib-only primitives) → core (interfaces + values + error codes) → service (implementations) → pkg/v1 (stable public alias layer) → framework. Each layer is grouped by the same families — crypto, security, net, proc, observe, data, app (ADR 0155). Dependency direction enforced on the build graph by scripts/check-layer-deps.sh (ADR 0068).
  • Typed errors throughout — fmt.Errorf / errors.New are banned in production code. Every error carries a wire-safe Public message and a log-only Private envelope. make guard gates it: the SDK runs its own sdkguard rule SDK002 over its production tree in make lint and CI. And every code is declared in one place — the core package at the path of the engine that raises it, so a domain's codes are found together and its public sentinels all alias the core (ADR 0160, gated by scripts/pre-commit/check-core-symmetry.sh).
  • One Marshal/Unmarshal for everything — text, binary, base-encoded — codec.Marshal(format, v) works the same way regardless of the underlying wire shape.
  • The rules are checkable from outside — the conventions this SDK states in its ADRs are enforced on your codebase too, by a tool the SDK ships: 
    go run github.com/kitsunium/sdk/tools/sdkguard@latest -level=invariant ./...
    It catches the defects that never announce themselves — a second logging pipeline beside the SDK logger (two thresholds, two formats, half-stamped records), stdout used as a log destination under a stdio protocol, a logger.Version assigned at runtime. Rules target constructs, never imports, so *slog.Logger fields and fmt.Fprintln(os.Stdout, …) stay legitimate. It also warns — without failing your build — when your go.mod pins an SDK older than the latest release, which matters here because a patch is cut whenever an internal package changes, carrying fixes no public-API changelog would show. See ADR 0033 and tools/sdkguard/CLAUDE.md.
  • A module per family, and a module per vendor — each pkg/v1/<family> is a module, internal/ is one shared module and the root holds the framework (ADR 0171); go.work adds the thirteen modules that require a vendor library: the framework's four connectors (three database engines and entitlement's ssh identity) and nine vendor modules under third-party/ — one per vendor, codec/yaml included (ADR 0157). Each can be built standalone with GOWORK=off, and bash scripts/ci/go-modules.sh lists them all. e2e/, tools/genindex/ and tools/sdkguard/ are auxiliary modules held deliberately outside it (adding them breaks Bazel's go_deps, which reads go.work) — build those with GOWORK=off.

Releases

Versioning follows semver and Go's sub-directory tag convention. Since ADR 0171 a release tags each module that changed, at its OWN version — vX.Y.Z for the root, pkg/v1/<family>/vX.Y.Z, internal/vX.Y.Z, third-party/<path>/vX.Y.Z, framework/connectors/<engine>/vX.Y.Z — in one atomic push, named by a release-manifest.json attached to ONE GitHub release. From v0.18.0 to v0.19.7 a release was one tag on the root, then holding pkg/ and internal/ (ADR 0162); v0.18.0 also cut pkg/v0.18.0 and framework/v0.18.0, tombstones that hold no package. The releases up to v0.17.0 were cut as pkg/vX.Y.Z with every other module in lockstep (ADR 0017, ADR 0147, ADR 0157): their tags are no longer on this repository — removed before ADR 0171 —, the Go module proxy still serves every one of their versions, and GOPROXY=direct cannot resolve them. A release is sized by the release:* label a maintainer sets on the pull request (ADR 0135). The full release workflow lives in ADR 0007 and the records that amend it (docs/adr/).

Documentation

Full versioned documentation lives at the docs portal (run make serve from the repo root, or browse the published deployment). Highlights:

  • Concepts — the 4-layer model, error semantics, codec dispatch
  • Changelog — auto-generated from git log per release
  • Per-package reference — codec, errs, logger with their full Go doc surfaces
  • ADRs — architecture decisions, reachable from the "For contributors ↗" footer link

Repository layout

internal/        stdlib-only primitives (kernel) + domain interfaces, values and codes (core)
                 + concrete impls (service), grouped by family in each layer (ADR 0155)
pkg/v1/          stable public API — type aliases + ergonomic helpers
docs/            ADRs + the Astro-based docs site
scripts/release/ release tooling — see ADR 0007
tools/           build-time helpers (workspace_status, genindex, alloc-lane-targets)
                 + sdkguard/ — consumer-facing rule enforcement (ADR 0033)
framework/       the layer above pkg/v1 a product imports (ADR 0147), the
                 distribution mechanisms and their ssh connector included (ADR 0158)
third-party/     opt-in vendor integrations, one Go module per vendor (ADR 0157)
e2e/             real-kernel conformance harness + the Docker-backed integration
                 suites (auxiliary module, GOWORK=off)

Verification

make build       # bazel mod tidy + gazelle + gofumpt + bazel build //...
make test        # every *_test target green incl. AST audits
make test-alloc  # race-off allocation gates (the only lane running //go:build !race tests)
make lint        # drift check (read-only): mod tidy + gazelle + gofumpt + guard + doc links + ktn-linter + the guards
                 #   (alloc-lane and audit coverage, domain docs, core symmetry, package docs, BENCH.md, error codes) + layer firewall
make guard       # sdkguard over the SDK's own tree: the invariants (ADR 0033), and SDK002 over production code (rule 2)
make bench       # regenerate codec BENCH.md from real Go benchmarks

Benchmarks

Kernel hot-path benchmarks live next to their source as internal/kernel/**/*_bench_test.go. Run them via:

make sdk-bench          # steady-state numbers → .bench.out (benchstat-friendly)
make sdk-bench-profile  # CPU / mem / block / mutex profiles → profiles/
make sdk-bench-compare  # benchstat A/B comparison vs a recorded .bench.main.out

See docs/BENCHMARK-TEMPLATE.md for the bench conventions (white-box package, b.Loop(), mandatory b.ReportAllocs(), _Parallel variants, and the allocation budgets the CI gate enforces).

Those budgets are checked by the race-off allocation lane — make test-alloc, whose target list lives in tools/alloc-lane-targets.txt. A test carrying //go:build !race is invisible to the race suite, so that lane is its only gate; scripts/pre-commit/check-alloc-lane-coverage.sh fails the build if such a test exists in a package the lane does not cover.

License

MIT — see LICENSE for the full text.

Directories

Path Synopsis
framework module
app
Package app — who may call an operation: the principal, the rules and their checks.
 Package app — who may call an operation: the principal, the rules and their checks.
app/apptest
Package apptest runs a product in its own tests as production runs it: on a data directory, where the framework seals what it keeps at rest, a transaction writes files and a rollback writes them back, a store's retention erases and folds what it overwrote, and a restart reads everything back — none of which a product kept in memory (app.InMemory) ever meets: the framework seals nothing in memory.
 Package apptest runs a product in its own tests as production runs it: on a data directory, where the framework seals what it keeps at rest, a transaction writes files and a rollback writes them back, a store's retention erases and folds what it overwrote, and a restart reads everything back — none of which a product kept in memory (app.InMemory) ever meets: the framework seals nothing in memory.
app/config/toml
Package toml lets a kit product read TOML configuration files — config/config.toml, config/<env>.toml — as it reads JSON ones.
 Package toml lets a kit product read TOML configuration files — config/config.toml, config/<env>.toml — as it reads JSON ones.
app/config/yaml
Package yaml lets a kit product read YAML configuration files — config/config.yaml, config/<env>.yaml, and .yml — as it reads JSON ones.
 Package yaml lets a kit product read YAML configuration files — config/config.yaml, config/<env>.yaml, and .yml — as it reads JSON ones.
app/jobs
Package jobs plugs kit's jobs in: the work a service declares on a schedule — every period (Service.Every) or on a five-field cron expression (Service.Cron) —, which the SDK's scheduler fires on the app's clock.
 Package jobs plugs kit's jobs in: the work a service declares on a schedule — every period (Service.Every) or on a five-field cron expression (Service.Cron) —, which the SDK's scheduler fires on the app's clock.
app/mail
Package mail plugs kit's mailers in: the outbox a mailer keeps — the SDK's mail spool, sealed on the database that keeps the mailer's service, else in the data directory or in memory — and the transports that empty it, the SDK's SMTP transport and its capture transport.
 Package mail plugs kit's mailers in: the outbox a mailer keeps — the SDK's mail spool, sealed on the database that keeps the mailer's service, else in the data directory or in memory — and the transports that empty it, the SDK's SMTP transport and its capture transport.
app/otlp
Package otlp plugs the framework's OTLP export in: the product's traces and the metrics the framework derives from them, each signal kept in a durable queue of its own — the SDK's app/forward over its data/queue, in the data directory, or on the product's database when otlp-database names one, which needs framework/app/queue too — and forwarded to an OpenTelemetry collector over OTLP/HTTP, retried on a backoff, a Retry-After waited in full.
 Package otlp plugs the framework's OTLP export in: the product's traces and the metrics the framework derives from them, each signal kept in a durable queue of its own — the SDK's app/forward over its data/queue, in the data directory, or on the product's database when otlp-database names one, which needs framework/app/queue too — and forwarded to an OpenTelemetry collector over OTLP/HTTP, retried on a backoff, a Retry-After waited in full.
app/queue
Package queue plugs kit's queues in: the queues of the topics a service declares and of their subscriptions, of its watches and of its queued commands, and the outbox of a mailer on a database — the brokers the SDK's queue runs them on, in memory, in the data directory or on a database, and their consumers.
 Package queue plugs kit's queues in: the queues of the topics a service declares and of their subscriptions, of its watches and of its queued commands, and the outbox of a mailer on a database — the brokers the SDK's queue runs them on, in memory, in the data directory or on a database, and their consumers.
app/server
Package server makes a kit app in the server profile — the default — serve HTTP: its endpoints, its frontends and its health probes, on the SDK's server engine.
 Package server makes a kit app in the server profile — the default — serve HTTP: its endpoints, its frontends and its health probes, on the SDK's server engine.
app/store
Package store plugs kit's stores in: the stores a service declares, the databases a product keeps them in and their migrations, app.Transact on a database, sealing at rest, history, revisions, trash, retention, holds, the privacy journal, Records and `data copy` — the engines the SDK's document store and sql run them on.
 Package store plugs kit's stores in: the stores a service declares, the databases a product keeps them in and their migrations, app.Transact on a database, sealing at rest, history, revisions, trash, retention, holds, the privacy journal, Records and `data copy` — the engines the SDK's document store and sql run them on.
app/storetest
Package storetest is the conformance suite of the framework's stores (ADR 0004): what a store does on every backend — in memory, in the data directory, on each database engine —, run by the framework's tests on memory, files and the framework's fake database, and by each engine module's tests on its engine.
 Package storetest is the conformance suite of the framework's stores (ADR 0004): what a store does on every backend — in memory, in the data directory, on each database engine —, run by the framework's tests on memory, files and the framework's fake database, and by each engine module's tests on its engine.
app/studio
Package studio serves, in dev, the read-only API the kit tool's Studio reads: the graph and its event stream, traces, instances and items, the source, the dev tools — the process, the databases, goroutines, the heap profile, logs, the mailbox, former values.
 Package studio serves, in dev, the read-only API the kit tool's Studio reads: the graph and its event stream, traces, instances and items, the source, the dev tools — the process, the databases, goroutines, the heap profile, logs, the mailbox, former values.
app/workflow
Package workflow plugs kit's workflows in: the state machines a service declares over the entities of its stores — their event, timer and guard transitions, their hooks and their loop —, which the SDK's statemachine runs.
 Package workflow plugs kit's workflows in: the state machines a service declares over the entities of its stores — their event, timer and guard transitions, their hooks and their loop —, which the SDK's statemachine runs.
entitlement
Package entitlement verifies a machine's entitlement to run a product: local key material plus a vendor-signed roster, turned into a grant or a typed refusal.
 Package entitlement verifies a machine's entitlement to run a product: local key material plus a vendor-signed roster, turned into a grant or a typed refusal.
gate
Package gate decides whether one invocation of a distributed binary may run.
 Package gate decides whether one invocation of a distributed binary may run.
git
Package git answers what a branch changed and what a working tree is at, by shelling out to the git binary.
 Package git answers what a branch changed and what a working tree is at, by shelling out to the git binary.
internal/app
Package app — who may call an operation: the principal, the rules and their checks.
 Package app — who may call an operation: the principal, the rules and their checks.
internal/app/jobengine
Package jobengine is what framework/app/jobs plugs into kit: the scheduler the framework's jobs run on — the SDK's scheduler, on the app's clock — and the schedules it reads from a job's declaration, a period or a five-field cron expression (ADR 0179 §1, step 7).
 Package jobengine is what framework/app/jobs plugs into kit: the scheduler the framework's jobs run on — the SDK's scheduler, on the app's clock — and the schedules it reads from a job's declaration, a period or a five-field cron expression (ADR 0179 §1, step 7).
internal/app/mailengine
Package mailengine is what framework/app/mail plugs into kit: the outbox the framework's mailers keep — the SDK's mail spool, on the database that keeps the mailer's service in the queue subsystem's sealed broker, else in the data directory or in memory — and the transports that empty it, the SDK's SMTP transport and its capture transport (ADR 0179 §1, step 6).
 Package mailengine is what framework/app/mail plugs into kit: the outbox the framework's mailers keep — the SDK's mail spool, on the database that keeps the mailer's service in the queue subsystem's sealed broker, else in the data directory or in memory — and the transports that empty it, the SDK's SMTP transport and its capture transport (ADR 0179 §1, step 6).
internal/app/otlpengine
Package otlpengine is what framework/app/otlp plugs into the framework: the export app.OTLP declares — the product's spans and the metrics the framework derives from them, each signal kept in a durable queue of its own (the SDK's app/forward over its data/queue, in the data directory, else in memory) and forwarded to an OpenTelemetry collector over OTLP/HTTP, or to the product's own sender (issue #483, ADR 0185).
 Package otlpengine is what framework/app/otlp plugs into the framework: the export app.OTLP declares — the product's spans and the metrics the framework derives from them, each signal kept in a durable queue of its own (the SDK's app/forward over its data/queue, in the data directory, else in memory) and forwarded to an OpenTelemetry collector over OTLP/HTTP, or to the product's own sender (issue #483, ADR 0185).
internal/app/plug
Package plug is where the framework's opt-in subsystems plug in: the HTTP engine, the frontends' file server and the process sampler of the runtime graph (framework/app/server), the Studio — the tool's variables, its routes and the framework's sentences in the languages after English (framework/app/studio) —, the stores and the databases (framework/app/store), the queues (framework/app/queue), the workflows (framework/app/workflow), the mailers (framework/app/mail), the jobs (framework/app/jobs).
 Package plug is where the framework's opt-in subsystems plug in: the HTTP engine, the frontends' file server and the process sampler of the runtime graph (framework/app/server), the Studio — the tool's variables, its routes and the framework's sentences in the languages after English (framework/app/studio) —, the stores and the databases (framework/app/store), the queues (framework/app/queue), the workflows (framework/app/workflow), the mailers (framework/app/mail), the jobs (framework/app/jobs).
internal/app/queueengine
Package queueengine is what framework/app/queue plugs into kit: the brokers the framework's consumers' queues run on — the SDK's queue in memory, in the data directory and over SQL, a mailer's outbox on a database sealed in front of the SQL one —, the consumer that delivers them, and the migration of a queue's table (ADR 0179 §1, step 4).
 Package queueengine is what framework/app/queue plugs into kit: the brokers the framework's consumers' queues run on — the SDK's queue in memory, in the data directory and over SQL, a mailer's outbox on a database sealed in front of the SQL one —, the consumer that delivers them, and the migration of a queue's table (ADR 0179 §1, step 4).
internal/app/serverengine
Package serverengine is what framework/app/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 serverengine is what framework/app/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).
internal/app/storeengine
Package storeengine is what framework/app/store plugs into kit: the engines the framework's stores run on — the SDK's document store in memory, in the data directory and over SQL —, the framework's scope on a database — the SDK's transaction manager, its check and its migrator — and the migrations of the framework's tables (ADR 0179 §1).
 Package storeengine is what framework/app/store plugs into kit: the engines the framework's stores run on — the SDK's document store in memory, in the data directory and over SQL —, the framework's scope on a database — the SDK's transaction manager, its check and its migrator — and the migrations of the framework's tables (ADR 0179 §1).
internal/app/studioengine
Package studioengine is what framework/app/studio plugs into the framework (ADR 0179 §1, step 8; ADR 0180 §4, step 1): the Studio's routes, their guard and their handlers — the graph, the live events as a Server-Sent Events stream (the SDK's net/sse), traces, source, instances, items, and the dev tools with the profiler (the SDK's profiling) —, the tool's variables the framework dev and the Studio set, and the framework's sentences in the languages after English — the catalogues the Studio shows its reader's language from, compiled by the SDK's i18n (Q6).
 Package studioengine is what framework/app/studio plugs into the framework (ADR 0179 §1, step 8; ADR 0180 §4, step 1): the Studio's routes, their guard and their handlers — the graph, the live events as a Server-Sent Events stream (the SDK's net/sse), traces, source, instances, items, and the dev tools with the profiler (the SDK's profiling) —, the tool's variables the framework dev and the Studio set, and the framework's sentences in the languages after English — the catalogues the Studio shows its reader's language from, compiled by the SDK's i18n (Q6).
internal/app/workflowengine
Package workflowengine is what framework/app/workflow plugs into kit: the engine the framework's workflows run on — the SDK's statemachine, instantiated once, over the framework's entity and the state's spelling (ADR 0179 §1, step 5, Q3) —, its loop of timers and guards, and the conversions between the engine's values and plug's.
 Package workflowengine is what framework/app/workflow plugs into kit: the engine the framework's workflows run on — the SDK's statemachine, instantiated once, over the framework's entity and the state's spelling (ADR 0179 §1, step 5, Q3) —, its loop of timers and guards, and the conversions between the engine's values and plug's.
internal/core/entitlement
Package entitlement — the error-code range this domain owns (framework/connectors/ssh block).
 Package entitlement — the error-code range this domain owns (framework/connectors/ssh block).
internal/core/gate
Package gate — the dotted-quad code range this domain owns.
 Package gate — the dotted-quad code range this domain owns.
internal/core/git
Package git — the error-code range owned by this domain (ADR 0005 §Registry).
 Package git — the error-code range owned by this domain (ADR 0005 §Registry).
internal/core/selfupdate
Package selfupdate — the error-code range owned by this domain (ADR 0005 §Registry).
 Package selfupdate — the error-code range owned by this domain (ADR 0005 §Registry).
internal/service/entitlement
Package entitlement — the trust anchors this verifier accepts, and why there is more than one of them.
 Package entitlement — the trust anchors this verifier accepts, and why there is more than one of them.
internal/service/gate
Package gate — the classifier behind framework/gate.
 Package gate — the classifier behind framework/gate.
internal/service/git
Package git — the changed set: which files, line ranges and directories a branch touched.
 Package git — the changed set: which files, line ranges and directories a branch touched.
internal/service/selfupdate
Package selfupdate replaces the running binary with a newer signed release.
 Package selfupdate replaces the running binary with a newer signed release.
model
Package model is the Product Graph: the one data shape every part of the framework agrees on.
 Package model is the Product Graph: the one data shape every part of the framework agrees on.
model/internal/core
Package core is the Product Graph under the names the role rule asks for: every struct carries its role (NodeEntity, GraphMessage, EndpointSpec, …).
 Package core is the Product Graph under the names the role rule asks for: every struct carries its role (NodeEntity, GraphMessage, EndpointSpec, …).
selfupdate
Package selfupdate replaces the running binary with a newer signed release.
 Package selfupdate replaces the running binary with a newer signed release.
telemetry
Package telemetry — the exporter: a bounded ring producers never wait on, drained to the clients attached to a private socket, which it never reads.
 Package telemetry — the exporter: a bounded ring producers never wait on, drained to the clients attached to a private socket, which it never reads.
connectors/mysql module
connectors/postgres module
connectors/sqlite module
connectors/ssh module
internal module
core module
kernel module
service module
pkg module
v1/app module
v1/clock module
v1/collections module
v1/concur module
v1/crypto module
v1/data module
v1/errs module
v1/net module
v1/observe module
v1/proc module
v1/security module
third-party
aws module
codec/hcl module
codec/protobuf module
codec/yaml module
db/redis module
db/writer/clickhouse module
db/writer/mysql module
db/writer/redis module
nats module
transform module
x-crypto module
tools
sdkguard module

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.