model

model

import "github.com/kitsunium/sdk/framework/model"

Package model is the Product Graph: the one data shape every part of the framework agrees on. The runtime serves it, a static analyzer produces it, a CLI prints it, a Studio draws it, and an AI agent or an editor extension reads it.

A graph is a projection: of the code for what runs, and — since the platform's ADR 0010 — of the design (a product's design/ directory) for what its structure must be. The design, not the graph, is authoritative on structure; the graph shows what the code is and where it differs from the design. Every node says where it was declared (Source) and every edge says how it is known: declared by construction (Edge.Declared), found in a handler body by a static analyzer (Edge.Static), or seen at runtime (Edge.Observed). A diagram that cannot say why an arrow exists is a drawing; this one can.

Identity

Every node has an ID, and the grammar of IDs is written here once — as patterns a schema generator can read (IDPattern, SegmentPattern, NamePattern) and as a parser (ParseID):

todos                              a service
moderation.intake                  a module's service
todos/endpoint/Create              a node of a service
todos/endpoint/GET /todos/{id}     an endpoint named by its route
binary:statusline                  a binary
binary:statusline/role/daemon      one of its process roles
library:textwidth                  a library shared between components
external                           the world outside the product

The runtime, the analyzer, the design files and the generator derive names with the same functions (NodeID, QualifiedService, RoleID), so two sides never disagree about what a declaration is called.

A contract

The JSON shape is a contract: Version is bumped on any change an older reader would misread.

Index

• Constants
• Variables
• func BinaryID(binary string) string
• func CompareSource(a, b Source) int
• func EdgeID(from string, kind EdgeKind, to, label string) string
• func IsEngine(backend string) bool
• func LibraryID(library string) string
• func Mermaid(g *Graph) string
• func ModulePrefix(name string) string
• func NodeID(service string, kind NodeKind, name string) string
• func QualifiedService(module, service string) string
• func RoleID(binary, role string) string
• func ServiceOf(id string) string
• func SplitDoc(text string) (string, map[string]string)
• func TableName(service, node, suffix string) string
• func UnderPrefix(prefix, path string) string
• func ValidContract(s string) bool
• func ValidName(s string) bool
• func ValidSegment(s string) bool
• type Adapter
• type Analysis
• type App
• type Architecture
• type AuthInfo
• type BinaryInfo
• type BootStep
• type Build
• type CLIInfo
• type Census
• type CodeBlock
• type CodeEffect
• type CodeFunc
• type CodeInfo
• type CodeStep
• type CodeUse
• type CommandInfo
• type Component
• type Connector
  • func ConnectorsOf(nodes []Node) []Connector
• type ConnectorInfo
  • func ConnectorCatalog() []ConnectorInfo
• type ConnectorKind
• type Container
• type Database
• type DevBuild
• type Diagnostic
• type Edge
• type EdgeKind
• type Edit
• type EndpointInfo
• type Erasure
• type Event
• type EventType
• type ExportedVersions
• type Field
• type File
• type FlameNode
• type Former
• type FrontendInfo
• type FuncCost
• type GoroutineGroup
• type Goroutines
• type Graph
  • func Merge(base, extra *Graph) *Graph
• type HTTPServer
• type HeldUntil
• type Hold
• type ID
  • func ParseID(s string) (ID, error)
• type IndexInfo
• type Instance
• type JobInfo
• type JournalCheck
• type JournalEntry
• type LibraryInfo
• type Link
• type ListenerInfo
• type LogRecord
• type Loop
• type LoopInfo
• type MailMessage
• type MailSummary
• type MailerInfo
• type Mechanic
• type Migration
• type MigrationSet
• type Mock
• type Module
• type ModuleVersion
• type Node
• type NodeCost
• type NodeKind
• type PasswordPolicy
• type Payload
• type Permission
• type Person
• type PersonalData
• type PhaseChange
• type Pool
• type Port
• type PortInfo
• type PresentationInfo
• type Privacy
• type Process
• type ProductRetention
• type Profile
• type QueryInfo
• type RecordFormer
• type RecordHistory
• type RecordVersion
• type RecordVersions
• type Register
• type RegisterStore
• type Retention
• type RoleInfo
• type Runtime
• type Schema
• type SecretInfo
• type SelectCase
• type Setting
• type Snippet
• type Source
• type Span
• type StateInfo
• type Stats
• type Step
• type StoreData
• type StoreErasure
• type StoreHistory
• type StoreInfo
• type StorePrivacy
• type SubscriptionInfo
• type System
• type TopicInfo
• type Trace
• type TransitionEvent
• type TransitionInfo
• type WakeSource
• type WorkflowInfo

Constants

Container kinds.

const (
    ContainerProcess string = core.ContainerProcess // the Go binary: every service, one process
    ContainerSPA     string = core.ContainerSPA     // a frontend: served by the process, run by a browser
    ContainerVolume  string = core.ContainerVolume  // the data directory: store files, queue files
    ContainerMemory  string = core.ContainerMemory  // data kept in the process's memory only
    // ContainerDatabase is a database the app declares (kit.Database):
    // "container:database:<name>", drawn as a cylinder.
    ContainerDatabase string = core.ContainerDatabase
)

What a port serves.

const (
    ServesHealth string = core.ServesHealth // the liveness and readiness probes
    ServesStudio string = core.ServesStudio // the Studio and its API, in dev
    ServesHTTP   string = core.ServesHTTP   // the product's own HTTP entry points
)

The kinds of CodeBlock.

const (
    BlockIf     string = core.BlockIf     // an if's first branch
    BlockElseIf string = core.BlockElseIf // an if's else-if branch
    BlockElse   string = core.BlockElse   // an if's last branch
    BlockCase   string = core.BlockCase   // a switch's or a select's case
    BlockLoop   string = core.BlockLoop   // a for or range loop's body
    BlockGo     string = core.BlockGo     // a go statement: runs beside the caller
    BlockDefer  string = core.BlockDefer  // a defer statement: runs when the function returns
    BlockFunc   string = core.BlockFunc   // a function literal: runs when it is called
    // BlockTransaction is the function a kit.Transact runs: its steps run in
    // one transaction, and the effects they make leave at its commit.
    BlockTransaction string = core.BlockTransaction
)

The roles of a connector, against the process boundary.

const (
    RoleInbound  string = core.RoleInbound
    RoleOutbound string = core.RoleOutbound
    RoleStorage  string = core.RoleStorage
)

The connectors kit ships.

const (
    ConnectorHTTP  string = core.ConnectorHTTP
    ConnectorMail  string = core.ConnectorMail
    ConnectorStore string = core.ConnectorStore
    ConnectorQueue string = core.ConnectorQueue
    // ConnectorDatabase is brought by a store a database keeps (ADR 0004):
    // kit.Database declares the database, an engine module reaches it.
    ConnectorDatabase string = core.ConnectorDatabase
)

The engines a database runs on (ADR 0004): one module each in kit's repository, the only code that imports its driver.

const (
    EnginePostgres string = core.EnginePostgres
    EngineMySQL    string = core.EngineMySQL
    EngineSQLite   string = core.EngineSQLite
)

Mail statuses.

const (
    MailQueued   string = core.MailQueued   // in the outbox, not yet handed to the transport
    MailSent     string = core.MailSent     // the transport accepted it (capture: kept for the mailbox)
    MailRetrying string = core.MailRetrying // the last attempt failed; another is scheduled
    MailDead     string = core.MailDead     // abandoned after its last attempt
)

The grammar of every ID a graph carries, written once. The runtime, the analyzer, the design files' JSON Schema and the Studio all read it from here: a second copy is how two sides come to derive different names for the same declaration (invariant 1 of the platform's kit).

id       = "external"
         | service
         | service "/" kind "/" name
         | "binary:" segment
         | "binary:" segment "/role/" segment
         | "library:" segment
service  = [ segment "." ] segment        ; "<module>.<service>"
segment  = [a-z][a-z0-9-]{0,62}
name     = [A-Za-z][A-Za-z0-9_.-]{0,62}
         | method " " path                 ; an endpoint named by its route

A module's service named like the module is the module's name alone (QualifiedService); every other service of a module is qualified.

const (
    // SegmentPattern is a service, module, binary, role or library name.
    SegmentPattern string = core.SegmentPattern
    // NamePattern is a node's name within its service and kind.
    NamePattern string = core.NamePattern
    // RoutePattern is the name of an endpoint declared without one: its
    // route, "GET /tasks/{id}".
    RoutePattern string = core.RoutePattern
    // ContractPattern is the versioned contract an [EdgeContracts] edge
    // carries: "render/v1".
    ContractPattern string = core.ContractPattern
    // BinaryScope prefixes the ID of a binary and of its roles.
    BinaryScope string = core.BinaryScope
    // LibraryScope prefixes the ID of a library.
    LibraryScope string = core.LibraryScope
)

Exposure says who may reach an endpoint.

const (
    // ExposePublic endpoints are routed on the product's HTTP listener.
    ExposePublic string = core.ExposePublic
    // ExposePrivate endpoints have no route: the implementation of a port
    // (Service.Implement), reached in process through its port. A graph kit
    // made before its operations were internal by default also marks so an
    // endpoint it kept off the listener.
    ExposePrivate string = core.ExposePrivate
)

How an exposure says it is open on purpose, when its operation declares no permission and no rule (EndpointInfo.Access).

const (
    // AccessAnyone is kit.Anyone(): whoever reaches the route may run the
    // operation.
    AccessAnyone string = core.AccessAnyone
    // AccessAnyUser is kit.AnyUser(): any signed-in user may run it — the
    // operation asks for one.
    AccessAnyUser string = core.AccessAnyUser
)

Authentication an endpoint asks for.

const (
    // AuthRequired endpoints run only for an authenticated caller; the others
    // are answered 401 before the handler runs.
    AuthRequired string = core.AuthRequired
    // AuthOptional endpoints run the auth handler when credentials are
    // present, and serve anonymous callers too.
    AuthOptional string = core.AuthOptional
)

Transition triggers.

const (
    // TriggerEvent is a transition fired by code, naming an event.
    TriggerEvent string = core.TriggerEvent
    // TriggerTimer is a transition fired after a duration in a state, or at
    // an instant the entity carries.
    TriggerTimer string = core.TriggerTimer
    // TriggerGuard is a transition fired when a condition on the entity
    // holds, checked each time the entity is written.
    TriggerGuard string = core.TriggerGuard
    // TriggerCreate is the entry of a new instance into the initial state.
    TriggerCreate string = core.TriggerCreate
)

How the start chose what a port calls: kit.Bind, else the one Service.Implement among the services the app mounts, else the port's fallback — or a test replaced the port.

const (
    // ViaBind is the app's kit.Bind.
    ViaBind string = core.ViaBind
    // ViaImplement is the one Service.Implement among the mounted services.
    ViaImplement string = core.ViaImplement
    // ViaFallback is the port's own kit.Fallback.
    ViaFallback string = core.ViaFallback
    // ViaReplace is a test's kit.Replace: a function answers in place of
    // whatever the port would call, and nothing is bound.
    ViaReplace string = core.ViaReplace
)

How a command is handled.

const (
    // ModeSync is handled on its caller's goroutine: Dispatch returns the
    // handler's result.
    ModeSync string = core.ModeSync
    // ModeQueued is sent to the background (kit.Queued): Dispatch returns
    // once the command's own queue accepted it, and a consumer handles it,
    // retried and dead-lettered.
    ModeQueued string = core.ModeQueued
)

Mail transports.

const (
    // TransportSMTP delivers to an SMTP relay.
    TransportSMTP string = core.TransportSMTP
    // TransportCapture keeps every message for the Studio's mailbox and
    // delivers nothing: the transport of dev and tests.
    TransportCapture string = core.TransportCapture
)

How a secret is made.

const (
    // SecretProvided is given by the operator: an SMTP URL, an API token.
    SecretProvided string = core.SecretProvided
    // SecretGenerated is made by kit and rotated on a schedule: a signing or
    // sealing key.
    SecretGenerated string = core.SecretGenerated
)

Where a running app found a secret.

const (
    // SecretFromEnv is the environment: the variable, or the file its _FILE
    // form names.
    SecretFromEnv string = core.SecretFromEnv
    // SecretFromFile is kit's encrypted file store: KIT_SECRETS=file:<dir>,
    // or .kit/secrets/dev in dev.
    SecretFromFile string = core.SecretFromFile
    // SecretFromMemory is a store in the process's memory: a test, or
    // KIT_SECRETS=memory. A generated secret is made again at every start.
    SecretFromMemory string = core.SecretFromMemory
    // SecretFromStore is a store the product's code gave kit.
    SecretFromStore string = core.SecretFromStore
)

Loop styles.

const (
    // LoopDeclared is Service.Loop: kit owns the wait — the wake sources are
    // data, so the diagram draws them — and the product owns the work.
    LoopDeclared string = core.LoopDeclared
    // LoopGoroutine is Service.Go: the product wrote the whole loop; kit
    // starts it, stops it, restarts it after a failure, and reads its select
    // statements to draw what it waits on.
    LoopGoroutine string = core.LoopGoroutine
)

Wake source kinds of a declared loop, and why a loop of kit's ran.

const (
    WakeInterval string = core.WakeInterval // a fixed period
    WakeDeadline string = core.WakeDeadline // a time the product computes after every run
    WakeTopic    string = core.WakeTopic    // any publish on a topic
    WakeStart    string = core.WakeStart    // once, when the app starts
    WakeManual   string = core.WakeManual   // Loop.Nudge, or the Studio
    WakeChange   string = core.WakeChange   // a write of the store a workflow runs over, or of one a watch hears
)

Select case kinds.

const (
    SelectTimer   string = core.SelectTimer   // a timer, ticker or time.After channel
    SelectDone    string = core.SelectDone    // ctx.Done(): the loop's way out
    SelectReceive string = core.SelectReceive // any other receive
    SelectSend    string = core.SelectSend    // a send
    SelectDefault string = core.SelectDefault // the default case: the select never blocks
)

What a field holds: the classes of a kit tag (ADR 0006).

const (
    // ClassPublic holds nothing personal and nothing secret: the question
    // was asked.
    ClassPublic string = core.ClassPublic
    // ClassPersonal holds data about an identifiable person: a name, an
    // address, a message a person wrote.
    ClassPersonal string = core.ClassPersonal
    // ClassSpecial holds the special categories of GDPR art. 9(1), or
    // criminal convictions (art. 10).
    ClassSpecial string = core.ClassSpecial
    // ClassSecret holds a credential: a password's hash, a token's digest.
    ClassSecret string = core.ClassSecret
)

Process profiles: what a role does with its process.

const (
    // ProfileServer serves HTTP until it is stopped: the platform's kit
    // product, and the only profile that opens a TCP listener.
    ProfileServer string = core.ProfileServer
    // ProfileCLI parses its arguments, runs once and exits with a typed
    // status. It starts no listener and no loop outlives it.
    ProfileCLI string = core.ProfileCLI
    // ProfileDaemon runs until it is stopped, or until it has been idle for
    // its declared time, and serves no HTTP: it answers on its listeners —
    // a private socket, a pipe — and runs its loops.
    ProfileDaemon string = core.ProfileDaemon
)

Listener networks.

const (
    // NetworkUnix is a Unix-domain socket, private to its owner.
    NetworkUnix string = core.NetworkUnix
    // NetworkPipe is a Windows named pipe, its DACL granting its owner only.
    NetworkPipe string = core.NetworkPipe
    // NetworkLocal is NetworkUnix where there is one, NetworkPipe on
    // Windows: what a product declares when it does not care which.
    NetworkLocal string = core.NetworkLocal
)

The modes of KIT_RETENTION.

const (
    // RetentionOn erases and deletes what is due: the default.
    RetentionOn string = core.RetentionOn
    // RetentionDryRun journals what the retention would do and changes
    // nothing: how a new retention is deployed over old data.
    RetentionDryRun string = core.RetentionDryRun
    // RetentionOff runs no retention, warned of at every start outside dev.
    RetentionOff string = core.RetentionOff
)

The gaps a register lists for a store that keeps personal data.

const (
    GapPurpose   string = core.GapPurpose   // no kit.Purpose
    GapRetention string = core.GapRetention // no retention, kit's or the product's: its personal data is kept forever
    GapSubject   string = core.GapSubject   // no subject field: no person can have their records
)

The security measures a register lists (point g).

const (
    // MeasureRedacted: the Studio, the spans and the logs never show a
    // personal, special or secret value.
    MeasureRedacted string = core.MeasureRedacted
    // MeasureHolds: a legal hold stops erasure and deletion.
    MeasureHolds string = core.MeasureHolds
    // MeasureJournal: every export, erasure, deletion and hold is journaled,
    // each entry chained to the previous one by SHA-256.
    MeasureJournal string = core.MeasureJournal
    // MeasureNotSealed: the store's classified members are in clear: it is
    // kept in memory, where nothing is at rest, or its members are plain.
    MeasureNotSealed string = core.MeasureNotSealed
    // MeasureSealed: its classified members are sealed at rest, AES-256-GCM
    // under per-subject data keys a person's erasure destroys (ADR 0006 §4).
    MeasureSealed string = core.MeasureSealed
)

The operations of the privacy journal.

const (
    JournalExport      string = core.JournalExport      // a person's records exported
    JournalRead        string = core.JournalRead        // a record read by a module, through kit.Records
    JournalErase       string = core.JournalErase       // a record's personal data cleared
    JournalDelete      string = core.JournalDelete      // a record removed
    JournalEraseFields string = core.JournalEraseFields // some fields of a record cleared, by a module
    JournalHold        string = core.JournalHold        // a hold placed on a record
    JournalRelease     string = core.JournalRelease     // a hold lifted
    JournalShred       string = core.JournalShred       // a subject's data key destroyed (ADR 0006, step 3)
)

Profile kinds.

const (
    ProfileCPU  string = core.ProfileCPU  // where CPU time went, sampled for a duration
    ProfileHeap string = core.ProfileHeap // where the live heap was allocated
)

Process phases, in the order a process goes through them.

const (
    PhaseStarting string = core.PhaseStarting
    PhaseServing  string = core.PhaseServing
    PhaseDraining string = core.PhaseDraining
    PhaseStopped  string = core.PhaseStopped
    PhaseFailed   string = core.PhaseFailed
)

Database states.

const (
    // DatabaseUnset: no URL, in dev. Its stores stay in the data directory
    // and nothing is opened.
    DatabaseUnset string = core.DatabaseUnset
    // DatabaseMemory: the app keeps its data in memory (kit.InMemory):
    // nothing is opened, no URL is read.
    DatabaseMemory string = core.DatabaseMemory
    // DatabaseOpen: the pool is open, its migrations ran, it answered its
    // check at start.
    DatabaseOpen string = core.DatabaseOpen
    // DatabaseFailed: the start could not open it, migrate it or reach it.
    DatabaseFailed string = core.DatabaseFailed
    // DatabaseClosed: not opened yet, or closed by the stop.
    DatabaseClosed string = core.DatabaseClosed
)

Where a setting's value comes from.

const (
    SettingEnv     string = core.SettingEnv     // an environment variable
    SettingOption  string = core.SettingOption  // the product's code: an AppOption
    SettingDefault string = core.SettingDefault // kit's default for the environment
    SettingStore   string = core.SettingStore   // the environment's secret store (a secret)
    SettingKitDev  string = core.SettingKitDev  // kit dev set the variable, for this launch
    SettingFile    string = core.SettingFile    // a configuration file of the product (Detail)
)

The settings kit reads, by the environment variable that sets each: kit's configuration reads them, the connectors and the architecture name them.

const (
    VarEnv          string = core.VarEnv
    VarAddr         string = core.VarAddr
    VarDataDir      string = core.VarDataDir
    VarStudio       string = core.VarStudio
    VarStudioRemote string = core.VarStudioRemote
    VarAnalyze      string = core.VarAnalyze
    VarTrustProxy   string = core.VarTrustProxy
    VarAllowedHosts string = core.VarAllowedHosts
    VarLogLevel     string = core.VarLogLevel
    VarSMTPURL      string = core.VarSMTPURL
    // VarRetention sets what the stores' retention loops do: on, dry-run
    // or off (ADR 0006).
    VarRetention string = core.VarRetention
    // VarDevForced is how kit dev tells the product which of the variables
    // above it set itself for this launch: their origin is kit dev.
    VarDevForced string = core.VarDevForced
)

Boot steps, in the order kit takes them.

const (
    BootConfig       string = core.BootConfig       // the environment and the options, read
    BootDeclarations string = core.BootDeclarations // what the services declare, checked
    BootMount        string = core.BootMount        // the services bound to the app
    BootRoutes       string = core.BootRoutes       // the routes of endpoints and frontends
    BootData         string = core.BootData         // the data directory, opened
    BootHandler      string = core.BootHandler      // health, the Studio, protection, observation
    BootComponents   string = core.BootComponents   // the lifecycle components, started in order
    BootServing      string = core.BootServing      // ready: the phase is serving
)

Component states.

const (
    ComponentPending  string = core.ComponentPending
    ComponentStarting string = core.ComponentStarting
    ComponentUp       string = core.ComponentUp
    ComponentStopping string = core.ComponentStopping
    ComponentDown     string = core.ComponentDown
    ComponentFailed   string = core.ComponentFailed
)

Loop kinds.

const (
    LoopJob       string = core.LoopJob       // a job, fired by the scheduler
    LoopTimer     string = core.LoopTimer     // a workflow's own loop: its timers and guards, when due
    LoopConsumer  string = core.LoopConsumer  // a subscription's consumer, a queued command's, or a mailer's outbox
    LoopHTTP      string = core.LoopHTTP      // the HTTP server's accept loop
    LoopScheduler string = core.LoopScheduler // the scheduler's own loop, which fires the jobs
    LoopWake      string = core.LoopWake      // a declared loop's wake cycle (Service.Loop)
    LoopRoutine   string = core.LoopRoutine   // a hand-written loop (Service.Go)
    LoopRotation  string = core.LoopRotation  // a generated secret's rotation, on its schedule
    LoopRetention string = core.LoopRetention // a store's retention: erases and deletes what is due (ADR 0006)
)

Loop provenances: who wrote the code that loops.

const (
    // ProvenanceLibrary loops are written by a library: net/http's accept
    // loop, the SDK scheduler, the SDK queue consumer.
    ProvenanceLibrary string = core.ProvenanceLibrary
    // ProvenanceKit loops are written by kit for a declaration: a workflow's
    // sweep, a declared loop's wake cycle.
    ProvenanceKit string = core.ProvenanceKit
    // ProvenanceProduct loops are written by hand in the product: Service.Go.
    ProvenanceProduct string = core.ProvenanceProduct
)

Loop states.

const (
    LoopWaiting    string = core.LoopWaiting    // blocked until its next wake
    LoopRunning    string = core.LoopRunning    // doing a run
    LoopRestarting string = core.LoopRestarting // failed, waiting out its backoff
    LoopStopped    string = core.LoopStopped
)

Span operations.

const (
    OpRequest     string = core.OpRequest     // an HTTP request served by an endpoint
    OpCall        string = core.OpCall        // an in-process call of an endpoint, or of a port
    OpRead        string = core.OpRead        // a store read
    OpWrite       string = core.OpWrite       // a store write
    OpPublish     string = core.OpPublish     // a topic publish
    OpDeliver     string = core.OpDeliver     // a subscription handling one message
    OpTransition  string = core.OpTransition  // a workflow transition
    OpRun         string = core.OpRun         // a job run, a loop run
    OpAuth        string = core.OpAuth        // the auth handler, in front of an endpoint
    OpSend        string = core.OpSend        // a mail put in the outbox
    OpDeliverMail string = core.OpDeliverMail // the outbox handing one mail to the transport
    OpSecret      string = core.OpSecret      // a secret's value or keys used: Value, Seal, Open, Sign, Verify
    OpDispatch    string = core.OpDispatch    // a command dispatched: its run, or its queuing for a queued one
    OpAsk         string = core.OpAsk         // a query asked
    OpHandle      string = core.OpHandle      // a queued command handled by its consumer, in the dispatcher's trace
    OpConnect     string = core.OpConnect     // a connection a listener accepted, handled until it closes
    OpCLI         string = core.OpCLI         // a short command-line command, run once
    // OpTransaction is a unit of work (kit.Transact, a command's, a
    // workflow's transition): its attrs say the database it belongs to —
    // "database", and "backend" as a store says it —, its "outcome", the
    // effects it held ("effects"), and "savepoint" for one nested in
    // another.
    OpTransaction string = core.OpTransaction
)

The outcomes of a transaction, as its span's "outcome" attribute says them.

const (
    // OutcomeCommit is a transaction that committed: its effects left.
    OutcomeCommit string = core.OutcomeCommit
    // OutcomeRollback is a transaction whose writes were undone: its effects
    // were dropped.
    OutcomeRollback string = core.OutcomeRollback
)

Span statuses.

const (
    StatusOK    string = core.StatusOK
    StatusError string = core.StatusError
)

const (
    // CodeInvalidID identifies an ID the grammar of [IDPattern] does not match.
    CodeInvalidID errs.Code = core.CodeInvalidID // 0.4.1.1
)

const (
    // ExternalID is the id of the node standing for the outside world.
    ExternalID string = core.ExternalID
)

MaxTableLen is the longest table name a store on a database takes, in bytes: the SDK's document store over SQL keeps its index rows in the table named after it with "___ix", within PostgreSQL's 63.

const MaxTableLen int = core.MaxTableLen

const (
    // MockReplace is the one mode a [Mock] has: a test's kit.Replace, a typed
    // function run in place of an operation's handler — or of what a port calls —
    // while the rest of its pipeline still runs. The Studio sets none (D13): it
    // shows the application, it does not act on it, so the respond, fail and
    // delay modes of the platform's kit have no representation here.
    MockReplace string = core.MockReplace
)

const (
    // PortOwnerKit is kit's own listener: the health probes, the Studio in
    // dev, and the product's HTTP when it declares any.
    PortOwnerKit string = core.PortOwnerKit
)

SealedPlaceholder is what the Studio receives in place of a value kit keeps sealed at rest — a record's member in the data browser, a former value —: never the value, nor its box (ADR 0006 §9). A value it opens and may not show is "[redacted]".

const SealedPlaceholder string = core.SealedPlaceholder

const (
    // Version is the schema version of every document in this package.
    //
    // Version 2 adds the auth, mailer and loop kinds, the sends and wakes edges,
    // the code level of every node ([CodeInfo]), the C4 context and containers
    // ([Architecture]) and the daemon's own machinery ([Runtime]).
    //
    // Version 3 adds the secret kind ([SecretInfo]), the uses edge, the secret
    // span operation, the rotation loop and the store origin of a setting.
    //
    // Version 4 is the one bump the decisions of issue #17 share. It adds the
    // port kind ([PortInfo]) and its binding, a declared edge from the port to
    // what it calls; the endpoint that implements a port
    // ([EndpointInfo].Implements), which has no method and no path; and the
    // replace mock mode ([MockReplace]). ADR 0004 adds the databases: the store's
    // database ([StoreInfo].Database), the database container, the database
    // connector and its adapters, [Runtime].Databases and [Setting].Database.
    // ADR 0008 adds the modules the app mounts ([Graph].Modules), the module of a
    // node ([Node].Module) and the Go module of a position outside the product's
    // ([Source].GoModule); and the watch, a subscription fed by stores: its mark
    // and the stores that feed it ([SubscriptionInfo].Mark,
    // [SubscriptionInfo].Stores), each drawing a declared delivers edge to it.
    // ADR 0005 adds the command and query kinds ([CommandInfo], [QueryInfo]),
    // the dispatches and asks edges, the endpoint that exposes one
    // ([EndpointInfo].Exposes), the read model ([StoreInfo].ReadModel), the
    // dispatch, ask and handle span operations and the dispatch and ask
    // controls.
    //
    // Version 5 is the first the SDK's framework module publishes (ADR 0147). It
    // adds what a product is made of beyond its services: the binary
    // ([KindBinary]) and its process roles ([KindRole]), the short CLI command
    // ([KindCLI]), the listener that is not HTTP ([KindListener]), the library
    // shared between components ([KindLibrary]) and the presentation
    // ([KindPresentation]); the edge between two roles of a product, which
    // carries a versioned contract ([EdgeContracts], [Edge].Contract); and the
    // grammar every ID follows, written once ([ID], [ParseID]). It removes what
    // the Studio no longer does (D13): the respond, fail and delay mock modes,
    // the control event and its payload — a [Mock] is a test's replacement only.
    Version int = core.Version
)

Variables

IDPattern is the whole grammar as one regular expression, anchored — the one the design files' JSON Schema publishes for an ID. Only an endpoint may be named by its route.

var IDPattern string = core.IDPattern

InvalidID is returned by ParseID for a string the ID grammar does not match. Its "part" field names what failed — the kind, the service name, the node name —, never the input.

var InvalidID *errs.Error = core.InvalidID

func BinaryID

func BinaryID(binary string) string

BinaryID is the ID of a binary.

func CompareSource

func CompareSource(a, b Source) int

CompareSource orders sources by root, file, then line.

func EdgeID

func EdgeID(from string, kind EdgeKind, to, label string) string

EdgeID builds the ID of an edge. The label is part of the identity: two transitions of one workflow fired from one endpoint are two edges.

func IsEngine

func IsEngine(backend string) bool

IsEngine reports whether backend names an engine a database runs on.

func LibraryID

func LibraryID(library string) string

LibraryID is the ID of a library.

func Mermaid

func Mermaid(g *Graph) string

Mermaid renders the architecture of a graph as a Mermaid flowchart: one subgraph per service — a module's inside the module's own, ADR 0008 —, one arrow per edge. GitHub renders it in Markdown, which makes a product's README carry its own, always regenerable, diagram.

Each kind has its shape: an endpoint a box (marked "auth" when it asks for a user; an implementation of a port by its name), a store a cylinder, a topic a flag, a subscription a parallelogram (a watch, ADR 0008, marked with the mark it watches — its stores' arrows say where from), a workflow a hexagon, a job a stadium, the auth handler a trapezoid — a gate —, a mailer a subroutine box, a declared loop a circle, a hand-written loop a double circle, a port an inverted trapezoid — a socket, UML's required interface —, a command a parallelogram leaning back — a subscription's leans forward —, marked "queued" when it waits in its queue, and a query a rhombus, a question. An arrow is solid when it exists by construction or was observed, dotted when only the code says so — or when it is a port's binding to its own fallback, the default the app may replace, as the Studio draws it.

func ModulePrefix

func ModulePrefix(name string) string

ModulePrefix is a module's default mount prefix: "/<name>/".

func NodeID

func NodeID(service string, kind NodeKind, name string) string

NodeID builds the ID of a node declared in a service. A service's own ID is its name.

func QualifiedService

func QualifiedService(module, service string) string

QualifiedService is the name a module gives a service it lists: the module's own name for the service named like it, "<module>.<service>" otherwise. The runtime and the analyzer both qualify with it.

func RoleID

func RoleID(binary, role string) string

RoleID is the ID of one process role of a binary.

func ServiceOf

func ServiceOf(id string) string

ServiceOf returns the service part of a node ID.

func SplitDoc

func SplitDoc(text string) (string, map[string]string)

SplitDoc splits a description into its default text and its translations.

A product documents a building block once, in Go, in its default language; a paragraph that starts with a language tag and a colon — "fr: Le cycle de vie d'un compte…" — is the same description in that language, until the next tag or the end:

// AccountLifecycle is the life of an account…
//
// fr: AccountLifecycle est la vie d'un compte…

It keeps Go's convention (the comment still starts with the name) and go doc prints both. Each text is joined into one line. A description whose only tagged paragraph is "en" uses it as the default.

func TableName

func TableName(service, node, suffix string) string

TableName is the table a database keeps a kit table in (ADR 0004): the service's name — qualified, for a module's —, two underscores and the node's name, then suffix, '-' and '.' written '_', lower case — "moderation.intake"'s store "cases" is moderation_intake__cases. A name the rule cannot keep as it is — upper case, longer than MaxTableLen, three underscores in a row, SQLite's own prefix — is cut and ends with a digest of the whole, so it stays one table's. The runtime and the analyzer name tables with it.

func UnderPrefix

func UnderPrefix(prefix, path string) string

UnderPrefix is a route declared at path, served under a module's mount prefix: "/reports" under "/moderation/" is "/moderation/reports", and under "/" it stays "/reports".

func ValidContract

func ValidContract(s string) bool

ValidContract reports whether s names a versioned contract: "render/v1".

func ValidName

func ValidName(s string) bool

ValidName reports whether s is a legal node name. An endpoint named by its route is legal as an ID but is not a name a declaration may give.

func ValidSegment

func ValidSegment(s string) bool

ValidSegment reports whether s is a legal service, module, binary, role or library name.

type Adapter

Adapter is a module a connector plugs a product in through: an engine, imported by the product's main to reach a database, and the only code of the product that imports its driver.

type Adapter = core.AdapterMessage

type Analysis

Analysis reports the status of static analysis. It says whether the analyzer ran, how long it took, and the error that stopped it.

type Analysis = core.AnalysisResult

type App

App identifies the product and the machine that described it. It names the module, the environment and the build the graph was taken from.

type App = core.AppMessage

type Architecture

Architecture is the product at the two outer levels of the C4 model.

Context (level 1) is the product as one box, the people who use it and the systems it depends on. Containers (level 2) is what the product is deployed as: the process, the frontend its browser runs, the volume its data lives on. Components (level 3) are the nodes, grouped by service; code (level 4) is each node's CodeInfo.

kit derives all of it from the declarations — a frontend implies a person with a browser, a mailer an SMTP relay, a data directory a volume, a database its own container — so it is exactly as true as the rest of the graph.

type Architecture = core.ArchitectureMessage

type AuthInfo

AuthInfo describes the app's authentication handler. Credentials says what it reads from a request; Endpoints are the ones behind it.

type AuthInfo = core.AuthSpec

type BinaryInfo

BinaryInfo is one executable the product ships: the Node.Binary of a KindBinary node, naming its roles.

type BinaryInfo = core.BinarySpec

type BootStep

BootStep is one step of the start, as it ran. It carries when it began, how long it took and, when it failed, its error.

type BootStep = core.BootStepMessage

type Build

Build is what a binary was built from, at its three levels. Its three levels are the Go toolchain, the main module and the modules it depends on.

type Build = core.BuildMessage

type CLIInfo

CLIInfo is a short command-line command: the Node.CLI of a KindCLI node, the words that run it.

type CLIInfo = core.CLISpec

type Census

Census is a workflow's population per state. It counts the instances in each state when the census was taken.

type Census = core.CensusMessage

type CodeBlock

CodeBlock is a block of a function that decides whether, or how many times, the steps under it run.

type CodeBlock = core.CodeBlockMessage

type CodeEffect

CodeEffect is one call on a building block, inside a function. It names the node it reaches and the edge kind that call draws.

type CodeEffect = core.CodeEffectMessage

type CodeFunc

CodeFunc is one function of the module a node's code reaches. Its steps are listed in the order they run, under the blocks that guard them.

type CodeFunc = core.CodeFuncMessage

type CodeInfo

CodeInfo is the code a node runs, as the static analysis read it: the fourth and innermost level of the C4 model. The entry is the function the node runs — an endpoint's handler, a subscription's, a loop's — and Funcs are the functions of the module it reaches, each with what it calls and what it does to other nodes.

type CodeInfo = core.CodeResult

type CodeStep

CodeStep is one thing a function does: a call to another function of the module, a call on a building block, or a call into the SDK — under the innermost block that guards it.

type CodeStep = core.CodeStepMessage

type CodeUse

CodeUse is one SDK function a node's code calls. Sites are where the node's code calls it, so a reader sees what it leans on.

type CodeUse = core.CodeUseMessage

type CommandInfo

CommandInfo describes a command: an operation that changes something. It carries its input and result schemas, its handler, its queue and who may dispatch it.

type CommandInfo = core.CommandSpec

type Component

Component is one lifecycle component: brought up in order, taken down in reverse.

type Component = core.ComponentMessage

type Connector

Connector is something a product plugs into, as the product declares it: how it is reached, what it reaches out to, where it keeps its data. The Studio shows a connector's pages and widgets only when the product has one: a command-line tool has no requests to list, a service without a mailer no mailbox.

A connector says what the code declares, never what an environment supplies. The relay a mailer delivers through, the directory a store writes to, the address kit listens on are facts of the running environment — MailerInfo, StoreInfo, the Architecture and Runtime carry those. So a connector is a pure function of the nodes (ConnectorsOf), and never moves a graph's revision.

type Connector = core.ConnectorMessage

func ConnectorsOf

func ConnectorsOf(nodes []Node) []Connector

ConnectorsOf derives the connectors a product uses from its nodes: an endpoint, a frontend or an auth handler means HTTP, a mailer mail, a store stores — and a database when one keeps it —, a topic, a subscription or a queued command queues. Sorted by ID.

type ConnectorInfo

ConnectorInfo is a connector kit can plug a product into, whether the product uses it or not: what it is, and the building blocks that bring it.

type ConnectorInfo = core.ConnectorSpec

func ConnectorCatalog

func ConnectorCatalog() []ConnectorInfo

ConnectorCatalog is every connector kit ships, sorted by ID: what a product may plug into.

type ConnectorKind

ConnectorKind groups connectors by what they are for.

type ConnectorKind = core.ConnectorKind

The kinds of connectors.

const (
    // ConnectorTransport is how the product is reached: HTTP.
    ConnectorTransport ConnectorKind = core.ConnectorTransport
    // ConnectorMessaging is what it sends and receives: mail, queues.
    ConnectorMessaging ConnectorKind = core.ConnectorMessaging
    // ConnectorData is where it keeps its data: stores, databases.
    ConnectorData ConnectorKind = core.ConnectorData
)

type Container

Container is one runnable or storage unit of the product. Its ID starts with "container:"; Nodes are the nodes that live in it.

type Container = core.ContainerMessage

type Database

Database is one database the app declares (kit.Database), as the running process found it. Its URL is never shown: where it was found, the engine, the address and the TLS mode are.

type Database = core.DatabaseMessage

type DevBuild

DevBuild is one build of `kit dev`: when, how long, and why. It lets the Studio say what changed and how long the reload took.

type DevBuild = core.DevBuildMessage

type Diagnostic

Diagnostic is a problem found while building the graph. It names the node or the file it is about, and how serious it is.

type Diagnostic = core.DiagnosticMessage

type Edge

Edge is one relation, with the evidence for it. Declared, Static and Observed say whether construction, the code or the runtime knows it.

type Edge = core.EdgeMessage

type EdgeKind

EdgeKind says how two nodes relate. It is a wire format — the graph's JSON and the Studio's TypeScript unions carry these names —, so it stays a string.

type EdgeKind = core.EdgeKind

The edge kinds.

const (
    // EdgeCalls targets an endpoint or a port. From a port, it is the port's
    // binding — what the port calls — and it is declared.
    EdgeCalls EdgeKind = core.EdgeCalls
    // EdgeReads targets a store the source reads from.
    EdgeReads EdgeKind = core.EdgeReads
    // EdgeWrites targets a store the source writes to.
    EdgeWrites EdgeKind = core.EdgeWrites
    // EdgePublishes targets a topic.
    EdgePublishes EdgeKind = core.EdgePublishes
    // EdgeDelivers goes from a topic to each of its subscriptions, and from a
    // store to each watch it feeds (ADR 0008). Declared.
    EdgeDelivers EdgeKind = core.EdgeDelivers
    // EdgeTransitions targets a workflow; Label carries the event.
    EdgeTransitions EdgeKind = core.EdgeTransitions
    // EdgePersists goes from a workflow to the store it lives in. Declared.
    EdgePersists EdgeKind = core.EdgePersists
    // EdgeSends targets a mailer: the source puts a message in its outbox.
    EdgeSends EdgeKind = core.EdgeSends
    // EdgeWakes goes from a topic to a declared loop it wakes. Declared.
    EdgeWakes EdgeKind = core.EdgeWakes
    // EdgeUses targets a secret whose value or keys the source uses.
    EdgeUses EdgeKind = core.EdgeUses
    // EdgeDispatches targets a command: the source dispatches it. From an
    // endpoint that exposes the command, or from a port bound to it, it is
    // declared.
    EdgeDispatches EdgeKind = core.EdgeDispatches
    // EdgeAsks targets a query: the source asks it. From an endpoint that
    // exposes the query, or from a port bound to it, it is declared.
    EdgeAsks EdgeKind = core.EdgeAsks
    // EdgeContracts goes from one process role to another it talks to —
    // through a socket, a pipe, a command line —, and names the versioned
    // contract they share in [Edge].Contract. It is the only edge between two
    // roles (D22). Declared.
    EdgeContracts EdgeKind = core.EdgeContracts
    // EdgeRuns goes from a role to what it runs: a CLI command, a listener,
    // an endpoint's server, a loop. Declared.
    EdgeRuns EdgeKind = core.EdgeRuns
    // EdgeImports goes from a component to a library it may import (D19).
    // Declared.
    EdgeImports EdgeKind = core.EdgeImports
    // EdgeRenders goes from a presentation to what it renders. Declared.
    EdgeRenders EdgeKind = core.EdgeRenders
)

type Edit

Edit is one change between two versions of a record, in RFC 6902's words: an add, a remove or a replace at a JSON pointer.

type Edit = core.EditMessage

type EndpointInfo

EndpointInfo describes an HTTP endpoint, or the implementation of a port. It carries the method and path, the request and response schemas, and its auth.

type EndpointInfo = core.EndpointSpec

type Erasure

Erasure is what kit.Erase did, store by store. Stores lists, store by store, what the erasure did there.

type Erasure = core.ErasureMessage

type Event

Event is one live event. Exactly one of the payload fields matching Type is set.

type Event = core.Event

type EventType

EventType names the kind of a live event. It is a wire format — the graph's JSON and the Studio's TypeScript unions carry these names —, so it stays a string.

type EventType = core.EventType

The live event types.

const (
    // EventHello opens every stream and carries the graph revision.
    EventHello EventType = core.EventHello
    // EventSpan reports one unit of work that finished on a node.
    EventSpan EventType = core.EventSpan
    // EventTransition reports a workflow instance changing state.
    EventTransition EventType = core.EventTransition
    // EventLifecycle reports a lifecycle component moving, or the process
    // changing phase.
    EventLifecycle EventType = core.EventLifecycle
    // EventLoop reports a loop run.
    EventLoop EventType = core.EventLoop
    // EventCensus reports a workflow's population per state.
    EventCensus EventType = core.EventCensus
    // EventGraph reports that the graph structure changed.
    EventGraph EventType = core.EventGraph
    // EventLog reports a log record written by product code, in dev.
    EventLog EventType = core.EventLog
    // EventMail reports a mail entering the outbox or changing status.
    EventMail EventType = core.EventMail
)

type ExportedVersions

ExportedVersions are the versions of one exported record.

type ExportedVersions = core.ExportedVersionsMessage

type Field

Field is one member of an object schema. It carries the JSON name, the schema of its value and the classes of its data.

type Field = core.FieldMessage

type File

File is one file a graph points at: its path, relative to its root — the product's module, or the Go module Source.GoModule names.

type File = core.FileMessage

type FlameNode

FlameNode is one frame of a flame graph. Its children are the frames it called; its value is the samples under it.

type FlameNode = core.FlameNodeMessage

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 = core.FormerMessage

type FrontendInfo

FrontendInfo describes static assets served by the product. It carries the path the assets are served under and where they are read from.

type FrontendInfo = core.FrontendSpec

type FuncCost

FuncCost is what one function cost. It carries the flat and cumulative samples of the function and where it lives.

type FuncCost = core.FuncCostMessage

type GoroutineGroup

GoroutineGroup is goroutines doing the same thing. They share one stack; Count says how many run it.

type GoroutineGroup = core.GoroutineGroup

type Goroutines

Goroutines is every goroutine of the process, grouped by what it runs. Each group names the node its stack runs in, when one does.

type Goroutines = core.GoroutinesResult

type Graph

Graph is the whole product. It is the JSON document the runtime serves and the analyzer writes; Version names its shape.

type Graph = core.GraphMessage

func Merge

func Merge(base, extra *Graph) *Graph

Merge enriches a graph with what another description of the same product knows. base is authoritative on which nodes exist — a runtime graph describes what the process actually serves —, on the modules it mounts, on what each of its ports calls and on which stores feed each of its watches: the app chose them when it started, where the analysis only reads the same rules over the whole module. extra, typically the static analysis, contributes documentation, handler ranges — an authorization function's too —, transition callers and the edges it found. Nodes only extra knows about are dropped: code that is compiled but not mounted in this app is not part of this product — save a node of a module's service the base mounts, which a package the binary does not link declares: a warning says so.

type HTTPServer

HTTPServer is the product's HTTP server, and whose loop serves it. Its address is the one it listens on; its loop is the node that runs it.

type HTTPServer = core.HTTPServer

type HeldUntil

HeldUntil is the hold a store declares on each of its records, until an instant the record carries.

type HeldUntil = core.HeldUntilSpec

type Hold

Hold is one record a legal hold keeps. It carries references only: never the record's key, its subject's identity, or the hold's reason, which kit keeps apart.

type Hold = core.HoldEvent

type ID

ID is a node's identity, parsed: the one grammar of IDPattern. Its String is the ID it was parsed from.

type ID = core.IDValue

func ParseID

func ParseID(s string) (ID, error)

ParseID reads an ID. It refuses anything IDPattern does not match, with InvalidID; the refusal never quotes the input, which may be anything a caller sent.

type IndexInfo

IndexInfo is one secondary index of a store. Its name is unique in the store; Unique says whether two records may share a key.

type IndexInfo = core.IndexSpec

type Instance

Instance is one entity's journey through a workflow. It carries the entity's key, its current state and the steps that brought it there.

type Instance = core.InstanceMessage

type JobInfo

JobInfo describes a scheduled job. It carries the fixed interval or the cron expression that schedules it.

type JobInfo = core.JobSpec

type JournalCheck

JournalCheck is what verifying the journal's chain found. A broken chain names the first entry whose hash does not follow.

type JournalCheck = core.JournalCheckMessage

type JournalEntry

JournalEntry is one operation of the privacy journal: what was done, where, by whom and when, with references only — never an identity, a value or a key. Each entry is chained to the previous one by SHA-256.

type JournalEntry = core.JournalEntryEvent

type LibraryInfo

LibraryInfo is a package shared between components (D19): the Node.Library of a KindLibrary node.

type LibraryInfo = core.LibrarySpec

type Link

Link is a relationship between two elements of the architecture. The process's link to a database, "Reads and writes", carries the database connector, and the store connector once stores live on it.

type Link = core.LinkMessage

type ListenerInfo

ListenerInfo is a listener that is not HTTP: the Node.Listener of a KindListener node — its network, its contract, who may connect.

type ListenerInfo = core.ListenerSpec

type LogRecord

LogRecord is one log record written by product code through kit.Log, kept in dev so the Studio can show a request's logs beside its spans.

type LogRecord = core.LogRecordMessage

type Loop

Loop is one recurring piece of the daemon's internal loop: a job, a workflow's timer sweep, a subscription's consumer, the HTTP accept loop, a declared or hand-written loop.

type Loop = core.LoopMessage

type LoopInfo

LoopInfo describes a loop node. Style says whether it is declared (kit owns the wait) or hand-written.

type LoopInfo = core.LoopSpec

type MailMessage

MailMessage is a whole captured mail, for the Studio's mailbox. It is kept by the capture transport of dev and tests only, never in production.

type MailMessage = core.MailMessage

type MailSummary

MailSummary is the name MailMessage embeds its summary under: the field a caller sets and reads is MailMessage.MailSummary, its JSON members promoted beside the body's.

type MailSummary = core.MailSummary

type MailerInfo

MailerInfo describes outbound mail. It carries the transport that empties the outbox and the outbox's counters.

type MailerInfo = core.MailerSpec

type Mechanic

Mechanic is a generic building block, backed by an SDK package, that a node composes. The catalog lists every mechanic kit offers; an endpoint's pipeline lists the ones it uses.

type Mechanic = core.MechanicMessage

type Migration

Migration is one versioned migration. Its Version orders it among the others; Name says what it does.

type Migration = core.MigrationMessage

type MigrationSet

MigrationSet is one set of migrations on a database — kit's own, the product's (kit.Migrations), a module's — with its own version table, and so its own lock.

type MigrationSet = core.MigrationSetMessage

type Mock

Mock is the replacement a test gave the app (MockReplace). It is set by a test only; the Studio shows it and never sets one (D13).

type Mock = core.MockMessage

type Module

Module is a module the app mounts: a Go module's services, released and mounted together like a bundle (ADR 0008). Everything a module declares is qualified with its name: its services are "<module>.<service>" — the one named like the module is "<module>" —, so its nodes are "<module>.<service>/<kind>/<name>" and carry Node.Module.

type Module = core.ModuleMessage

type ModuleVersion

ModuleVersion identifies one module of a build. Local and Modified say when the code that ran is not the published version.

type ModuleVersion = core.ModuleVersionMessage

type Node

Node is one building block. Its ID is its identity; exactly one of the kind-specific fields matching Kind is set.

type Node = core.NodeEntity

type NodeCost

NodeCost is what one node cost. It is the share of the profile's samples spent in the node's code.

type NodeCost = core.NodeCostMessage

type NodeKind

NodeKind is the closed set of building blocks a kit product is made of. It is a wire format — the graph's JSON and the Studio's TypeScript unions carry these names —, so it stays a string.

type NodeKind = core.NodeKind

The node kinds.

const (
    // KindService groups the nodes of one bounded context.
    KindService NodeKind = core.KindService
    // KindEndpoint is an HTTP endpoint with typed request and response.
    KindEndpoint NodeKind = core.KindEndpoint
    // KindStore is a typed, keyed collection of entities.
    KindStore NodeKind = core.KindStore
    // KindTopic is an asynchronous, at-least-once message channel.
    KindTopic NodeKind = core.KindTopic
    // KindSubscription consumes one topic.
    KindSubscription NodeKind = core.KindSubscription
    // KindWorkflow is a state machine over the entities of one store.
    KindWorkflow NodeKind = core.KindWorkflow
    // KindJob is scheduled work: a fixed interval or a cron expression.
    KindJob NodeKind = core.KindJob
    // KindFrontend is static assets served by the product.
    KindFrontend NodeKind = core.KindFrontend
    // KindExternal stands for everything outside the product.
    KindExternal NodeKind = core.KindExternal
    // KindAuth is the app's authentication handler: it turns a request's
    // credentials into a user, in front of every endpoint that asks for one.
    KindAuth NodeKind = core.KindAuth
    // KindMailer is outbound mail: a durable outbox, and the transport that
    // empties it — SMTP, or the capture of dev and tests.
    KindMailer NodeKind = core.KindMailer
    // KindLoop is a long-running loop of the daemon: declared (kit owns the
    // wait, the product the work) or hand-written (a goroutine kit supervises).
    KindLoop NodeKind = core.KindLoop
    // KindSecret is a secret the product declares: provided by the operator,
    // or generated by kit and rotated on a schedule. Its value is never in a
    // graph.
    KindSecret NodeKind = core.KindSecret
    // KindPort is an operation a service needs and does not implement: a
    // typed request, a typed response, a name. What it calls — another
    // service's endpoint, the app's binding, its own fallback — is decided
    // when the app starts, and drawn as a declared edge from the port.
    KindPort NodeKind = core.KindPort
    // KindCommand is an operation that changes something: a typed input, a
    // typed result, one handler, the pipeline of its kind. It is dispatched,
    // on its caller's goroutine or through its own queue.
    KindCommand NodeKind = core.KindCommand
    // KindQuery is an operation that reads and changes nothing: a typed
    // input, a typed result, one handler. It is asked.
    KindQuery NodeKind = core.KindQuery
    // KindBinary is one executable the product ships. It holds process
    // roles; its ID is "binary:<name>".
    KindBinary NodeKind = core.KindBinary
    // KindRole is one process role of a binary — "statusline" and
    // "statusline daemon" are two roles of one binary. Its root package is
    // generated wiring; two roles talk through their contract only. Its ID
    // is "binary:<binary>/role/<name>".
    KindRole NodeKind = core.KindRole
    // KindCLI is a short command-line command: it parses its arguments,
    // runs once and exits with a typed status.
    KindCLI NodeKind = core.KindCLI
    // KindListener accepts connections that are not HTTP: a private Unix
    // socket, a named pipe. It is an inbound port like an endpoint.
    KindListener NodeKind = core.KindListener
    // KindLibrary is a package shared between components, declared so the
    // components that use it are allowed to import it. Its ID is
    // "library:<name>".
    KindLibrary NodeKind = core.KindLibrary
    // KindPresentation turns a service's results into what a reader sees:
    // a rendered line, a page, a report.
    KindPresentation NodeKind = core.KindPresentation
)

type PasswordPolicy

PasswordPolicy is the policy of one secret field that holds a password's hash (Store.Passwords).

type PasswordPolicy = core.PasswordPolicyMessage

type Payload

Payload is the request and the response of a span, as JSON, in dev only. Every member whose name says it is a secret — password, token, secret, authorization, cookie… — or whose Go field is tagged kit:"secret" is replaced by "[redacted]", and each side is cut at 8 KiB.

type Payload = core.Payload

type Permission

Permission is what a caller needs to dispatch a command or to ask a query: that the app's policy lets it do Action to Resource (Allow).

type Permission = core.PermissionMessage

type Person

Person is a human user of the product. It is drawn at the edge of the C4 context view, outside every container.

type Person = core.PersonMessage

type PersonalData

PersonalData is a person's data as kit.Export gives it (GDPR art. 15 and 20): their records, store by store, with what art. 15(1) asks beside them.

type PersonalData = core.PersonalDataMessage

type PhaseChange

PhaseChange is one step of the daemon's life. It carries the phase entered, when it was entered, and why.

type PhaseChange = core.PhaseChangeEvent

type Pool

Pool is a database's connection pool, as database/sql counts it. It is sampled when the runtime state is read; its counters never move a revision.

type Pool = core.Pool

type Port

Port is an address a process listens on. Owner is the container that listens on it; Serves names what is reached through it.

type Port = core.PortMessage

type PortInfo

PortInfo describes a port: an operation a service needs and another implements.

type PortInfo = core.PortSpec

type PresentationInfo

PresentationInfo is what turns results into what a reader sees: the Node.Presentation of a KindPresentation node.

type PresentationInfo = core.PresentationSpec

type Privacy

Privacy is what a running app says of the personal data it keeps. It is the Privacy page's data: the register, the holds and the journal's state.

type Privacy = core.PrivacyMessage

type Process

Process is the Go process a product runs in. It carries the runtime's figures — goroutines, heap, GC, CPU — taken at At.

type Process = core.ProcessSpec

type ProductRetention

ProductRetention is a retention the product keeps itself, as it says it.

type ProductRetention = core.ProductRetentionSpec

type Profile

Profile is a pprof profile of the running product, folded onto its graph: every sample is attributed to the node whose code was running — through the pprof label kit puts on every handler, subscription, job and loop run, or, for the heap, which carries no label, through the node's code functions on the sample's stack.

type Profile = core.ProfileResult

type QueryInfo

QueryInfo describes a query: an operation that reads and changes nothing.

type QueryInfo = core.QuerySpec

type RecordFormer

RecordFormer is the former values of one exported record's fields. A personal or special field's former values are redacted, never exported in clear.

type RecordFormer = core.RecordFormerMessage

type RecordHistory

RecordHistory is what kit remembers of one record, as the Studio's data view shows it (GET /_kit/api/former): each field's former values, newest first, by the field's JSON pointer — a secret field's without their values, a personal or special one's redacted.

type RecordHistory = core.RecordHistoryMessage

type RecordVersion

RecordVersion is one version of a record whose store keeps revisions (ADR 0007 §3): its number, when the write that made it ran, who made it and which command, and the record as it was.

type RecordVersion = core.RecordVersionMessage

type RecordVersions

RecordVersions is a record's versions as the Studio's data view shows them (GET /_kit/api/revisions), and what changed between two.

type RecordVersions = core.RecordVersionsMessage

type Register

Register is the record of processing of GDPR art. 30(1), as far as the code knows it.

type Register = core.RegisterMessage

type RegisterStore

RegisterStore is one store's line in the register. It names the classes the store keeps, their purposes and their retention.

type RegisterStore = core.RegisterStoreMessage

type Retention

Retention is when kit erases or deletes a record: after a delay counted from an instant the record carries (After or Setting, and Since), or at an instant a function gives (At).

type Retention = core.RetentionSpec

type RoleInfo

RoleInfo is one process role of a binary: the Node.Role of a KindRole node — its profile, arguments, singleton and idle stop.

type RoleInfo = core.RoleSpec

type Runtime

Runtime is what a running process says about itself: the daemon's own state and its internal loop.

type Runtime = core.RuntimeMessage

type Schema

Schema describes a Go type as it appears on the wire. It is a JSON-Schema-like shape: a kind, its fields or elements, and its Go type.

type Schema = core.SchemaMessage

type SecretInfo

SecretInfo describes a declared secret: how it is made, where it lives, its versions — never its value.

type SecretInfo = core.SecretSpec

type SelectCase

SelectCase is one case of a select statement in a hand-written loop. The analyzer reads it from the loop's body; Kind says what the case waits on.

type SelectCase = core.SelectCaseMessage

type Setting

Setting is one configuration value kit read when the product started: kit's own, or one a service of the product declares.

type Setting = core.SettingMessage

type Snippet

Snippet is source code served to a reader of the graph. Focus and FocusEnd mark the lines a reader asked for, inside the lines served.

type Snippet = core.SnippetMessage

type Source

Source locates code. File is relative to its module's root; Line and EndLine bound the declaration.

type Source = core.SourceMessage

type Span

Span is a finished unit of work, attributed to a node. Only allow-listed, wire-safe fields travel: no URL, no query string, no private error text.

type Span = core.SpanMessage

type StateInfo

StateInfo is one state of a workflow. Terminal marks a state an instance stays in; Count is how many instances are in it.

type StateInfo = core.StateSpec

type Stats

Stats are observed counters for a node or an edge. They are counters: they never move a graph's revision.

type Stats = core.StatsMessage

type Step

Step is one transition in an instance's history. It carries the event, the states it went from and to, and when it fired.

type Step = core.StepEvent

type StoreData

StoreData is one store's records about a person. It is one part of what kit.Export gives a person about themselves.

type StoreData = core.StoreDataMessage

type StoreErasure

StoreErasure is one store's part of an erasure: the keys of the records erased, deleted, and held — left in place, as a legal hold asks. A key may be personal data, which the Studio and the logs never show.

type StoreErasure = core.StoreErasureMessage

type StoreHistory

StoreHistory is what a store remembers of its records. Fields names the fields it keeps former values of; Kept and Bytes weigh them.

type StoreHistory = core.StoreHistoryMessage

type StoreInfo

StoreInfo describes a store. It carries the entity's schema, its backend, its indexes, its privacy and its history.

type StoreInfo = core.StoreSpec

type StorePrivacy

StorePrivacy is what a store keeps of people: whom each record is about, why, for how long, and — on a runtime graph — what is held and due.

type StorePrivacy = core.StorePrivacyMessage

type SubscriptionInfo

SubscriptionInfo describes a subscription — or a watch (ADR 0008), a subscription whose deliveries come from stores instead of a topic.

type SubscriptionInfo = core.SubscriptionSpec

type System

System is a software system outside the product. Nodes are the product's nodes that talk to it; Technology says what it runs on.

type System = core.SystemMessage

type TopicInfo

TopicInfo describes a topic. It carries the message's schema; its subscriptions are the nodes it delivers to.

type TopicInfo = core.TopicSpec

type Trace

Trace is the spans sharing one trace ID, root first. The root span is the one with no parent in the trace; the others follow it.

type Trace = core.TraceMessage

type TransitionEvent

TransitionEvent is one workflow instance moving between states. It names the workflow, the entity, the event and the states it went from and to.

type TransitionEvent = core.TransitionEvent

type TransitionInfo

TransitionInfo is one arrow of a workflow. It names the event that fires it and the states it goes from and to.

type TransitionInfo = core.TransitionSpec

type WakeSource

WakeSource is one thing that wakes a declared loop. Kind says whether a topic, a period (Every) or a function wakes the loop.

type WakeSource = core.WakeSourceMessage

type WorkflowInfo

WorkflowInfo describes a state machine bound to a store. It carries the states and the transitions between them, and the store it lives in.

type WorkflowInfo = core.WorkflowSpec

Generated by gomarkdoc