beads/cmd/bd/serve.go
Julian Knutsen 4450fe99bb
feat(http): bd blocked over bd serve (blocked.list), plus bd blocked --flags [--raw] (#7649)
* feat(http): bd blocked over bd serve (blocked.list) through issueops.BlockedLister

`bd blocked` refused against an HTTP workspace: it called the legacy
GetBlockedIssues, which the HTTP backend stubs as unsupported. It now runs
one role on every route, and bd serve publishes that role.

- Role: issueops.BlockedLister.ListBlocked(BlockedRequest{ParentID, Labels,
  LabelsAny, ExcludeLabels}) -> BlockedResult{Items}. One body,
  internal/storage/issueops.ExecuteListBlockedInTx over the unchanged
  GetBlockedIssuesInTx; labels normalized in the role (BlockedFilter);
  Items never nil and in a total order (priority, created_at desc, id).
- Legs: DoltStore (read tx), EmbeddedDoltStore (read conn), uow (read unit
  of work through the use case's GetBlockedIssues, so the
  external-dependency uow decorator applies). Census: storage.DoltStorage
  gains BlockedLister(); HookFiringStore passes it through (a read),
  telemetry wraps it, uow.notifyingProvider, externaldeps.uowProvider and
  httpapi.timedProvider build it.
- externaldeps.Store.BlockedLister is built over its own GetBlockedIssues,
  so local `bd blocked` output is unchanged. Over a remote store it takes
  the server's listing when the server advertises
  policy.external_dependencies, else decorates the server's listing here
  through EdgeReader and BatchGetter (decorateBlocked, factored out of
  GetBlockedIssues).
- Wire: GET /v0/beads/blocked (listBlockedIssues; parent, label,
  label_any, exclude_label) answering BlockedPage {items, has_more} with
  the new x-go-type-pinned BlockedIssue schema, behind the new
  blocked.list token. apigen and the wire-shape golden regenerated; the
  golden diff is additive only, so wire_revision stays 2.
  Config.BlockedLister is a required role, wired in bd serve.
- Client: httpclient.Store.BlockedLister dials through Store.dispatch, so
  an older server is refused BEFORE the dial with *wire.CapabilityError
  naming blocked.list. The legacy Store.GetBlockedIssues rides the role
  (page and row cap applied to its answer) and leaves the unsupported
  shell. Divergence ledger row F-blocked retired.
- CLI: `bd blocked` takes BlockedLister() from the store on the direct
  routes and from the provider's BlockedListerSource on the proxied route;
  runBlockedProxiedServer is deleted. --json output is the same rows in
  the same order, [] when empty.

Tests: backend/conformance RunBlockedLister (10 cases: direct blocker,
child attributed to its blocked parent, closed blocker, wisp plane, pinned
status, parent filter, label filters with normalization, order, empty
slice, request not mutated) on dolt, embedded, uow and the served HTTP
client; httpapi handler tests (mapping, unknown/repeated params,
projection, capability); httpclient stub tests (pre-dial refusal naming
the token, encoding, projection, legacy door paging); skew and vocabulary
counts; TestE2E_BlockedOverHTTP (served `bd blocked --json` equals the
local command's after mapping ids and timestamps, member order included,
external blocker named, older-server refusal with no dial); corpus
gc-blocked re-marked and gc-blocked-parent added, both pending until the
reference server advertises blocked.list.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

* fix(blocked): pin server-side external decoration, refuse has_more, serve the legacy door over http

Review fixes for the blocked.list slice.

- Server-side external decoration is now pinned on the compositions bd
  serve answers from. TestWrapUOWProviderBlockedListerNamesExternalBlockers
  lists through the wrapped unit-of-work provider's own BlockedLister
  accessor (the bd serve provider path) and requires an external-only row
  and a mixed row to carry their external: refs; building that lister over
  the inner provider fails it. TestServedBlockedListerCarriesExternalRefs-
  WhenTheServerEnforces serves the store-shaped composition
  (externaldeps.Store.BlockedLister, policy advertised) and requires the
  operation's own answer, through the undecorated client role, to carry the
  refs, and the client's decorated chain to return it unchanged; serving
  the inner store's lister fails it.
- The client refuses an answer reporting has_more with the new typed
  httpclient.TruncatedListingError instead of returning a short listing:
  the operation has no cursor, and a caller reads a missing row as
  unblocked. The legacy door inherits it.
- externaldeps.Store.GetBlockedIssues over an http store reads the extra
  sources through the served roles (EdgeReader, BatchGetter) instead of the
  raw GetIssuesByIDs / GetDependencyRecordsForIssues the http backend
  refuses, and the decoration skips the source read when there is nothing
  to load. The legacy door on the CLI chain (bd mol stale, the wisp
  commands) now answers over http in both policy modes;
  TestServedLegacyGetBlockedIssuesThroughTheDecorator pins it, paging
  included. bd ready --explain still refuses on its other raw reads; the
  CHANGELOG says so.
- Docs: the spec and the retired F-blocked ledger row state that the
  listing is unpaged, bounded by the client's 32 MiB response limit
  (refused, never read in part), and that has_more is refused.
- Contract: new cases for waits-for and conditional-blocks blockers, no
  type exclusions (gate, epic), and a stale flag with no nameable blocker
  (on the legs that can write the column: dolt, embedded; skipped
  elsewhere with the reason). Order seeds explicit created_at values with
  five rows tied on priority and created_at, two of them wisps, so only the
  id tiebreak orders them; dropping the tiebreak now fails every run.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

* feat(blocked): bd blocked --flags, the blocked flag per id from stdin

`bd blocked --flags [--json]` reads ids from stdin, one per line (blank
lines and repeats ignored), and prints the blocked flag bd holds for each:
with --json, [{"id","is_blocked"}] in the order the ids were first given,
omitting an id that names no row on either plane, [] for no input. It is
the readiness column a consumer otherwise had to read with `bd sql`, so no
such consumer needs a local-only command.

It is the FLAG, not the listing: `bd blocked` narrows the stored flag to
rows it can name a blocker for, and --flags does not, so a row whose flag
is set with no nameable blocker reads true here and is absent from the
listing. Where the external-dependency policy applies, an unsatisfied
external: blocker sets the flag, as it keeps the row out of `bd ready`.

One library entry on every route: issueops.BlockedFlags over the route's
BlockingAnnotator (the store's accessor on dolt, embedded and HTTP, the
provider's on the proxied route). Over HTTP that is listBlockingAnnotations
with is_blocked behind dependencies.blocking.isBlocked; a server without
that token is refused before the dial, naming it. No wire change. The
listing's filter flags are refused with --flags rather than ignored.

Tests: TestE2E_BlockedFlagsOverHTTP (served JSON equals the local command's
after mapping ids to titles, unknown id omitted, repeat collapsed, [] on
empty stdin, filters refused; a stale-flagged row with no blocker reads
true and is absent from `bd blocked --json`, which fails if --flags is
derived from the listing; an older server's handshake refused naming the
token with no dial); TestProxiedServerBlocked/flags_reads_ids_from_stdin on
the proxied route; corpus gc-blocked-flags, pending until the reference
server advertises the token. CHANGELOG entry.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

* feat(blocked): bd blocked --flags --raw, the stored is_blocked column

`bd blocked --flags --raw [--json]` answers the stored is_blocked column
for each id read from stdin, exactly what reading is_blocked from the issues
and wisps tables returns, without the external-dependency policy: a row
blocked only by an unsatisfied external: ref reads false (the policy-aware
--flags reads true), and a stale flag reads true either way. Same output
shape as --flags. This lets a consumer move off a `bd sql` read of the
column with no change in what it reads. The default --flags is unchanged.

The role is taken from beneath every decorator: storage.UnwrapStore on the
direct routes, uow.UnwrapProvider on the proxied route. Over HTTP the
innermost store is the http client, whose annotation read is the server's
answer: against a server that does not advertise
policy.external_dependencies that answer is the column, and --raw is
served. A server that advertises it decorates the flag it answers, the v0
wire has no member asking it for the column, and the decorated flag cannot
be turned back into the column client-side, so --raw against such a server
is refused before the annotation read, naming the token, rather than
answered with the decorated flag. --raw without --flags is refused.

Tests: TestE2E_BlockedFlagsOverHTTP/raw_is_the_stored_column (served --raw
equals local --raw; the externally-blocked-only row reads true with --flags
and false with --raw on both; locally blocked rows agree; a stale-flagged
row reads true in both modes; --raw without --flags exits 1; a server
advertising the policy refuses --raw with no annotation request);
TestProxiedServerBlocked/flags_raw_is_the_stored_column; corpus
gc-blocked-flags-raw (pending until the reference server advertises
dependencies.blocking.isBlocked). Routing --raw through the decorated
annotator fails the e2e. CHANGELOG entry.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

* docs(changelog): bd blocked --flags --raw is for the local and proxied routes

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

* test(blocked): give the e2e gate-kid its own priority; document --flags answers closed ids

TestE2E_BlockedOverHTTP seeded gate-parent and gate-kid at one priority, so
when both landed in the same second their order fell to the generated ids,
which differ between the local and the served workspace: the comparison
failed intermittently. gate-kid now has its own priority. Ten runs on the
embedded lane pass.

bd blocked --flags answers a closed id too, with its stored flag; a SQL read
of the column filtered on status <> 'closed' leaves it out. Said in the
command's doc and the CHANGELOG.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

* fix(blocked): apply label filters to external-only blocked rows

The external-dependency policy appends a row blocked only by an
unsatisfied external: ref after the label query has run, so --label,
--label-any and --exclude-label never judged it: bd blocked and
GET /v0/beads/blocked listed it whatever its labels, on every route.
Both decorators now filter those rows by the request's labels. The uow
decorator reads them through GetMany, chunked at MaxGetManyIDs, so their
labels are hydrated; GetIssuesByIDs left them empty, which also printed
them unlabelled on the proxied route.

Review fixes (adopt-pr apply-fixes, iteration 1):
- major #1: label filters on external-only rows in the store and uow
  decorators, with absence-asserting arms in the unit, served httpclient
  (server- and client-enforced policy), e2e and proxied tiers; the spec
  and the role doc say such rows are narrowed like every other row.
- minor #2: the policy.external_dependencies token prose names the
  blocked listing (spec, routes.go, regenerated types.gen.go).
- minor #6: SERVE_RUNBOOK and the allowUnlimited comment record the
  blocked listing's unbounded whole-set answer and why.
- minor #10: BlockedLister telemetry-outermost and typed-unsupported pins
  beside the ReadyCounter pair, plus the externaldeps wrap pin.
- nit #9: F-blocked names --flags --raw's refusal against a server that
  applies the policy (ledger.go and the regenerated ledger doc).
- nit #11: the remote BlockedLister no longer builds a local lister it
  then discards.

Review fixes (adopt-pr apply-fixes, iteration 2; the review approved at
940 with one minor and two nits, none gating):
- minor (the --flags refusal list was unpinned): the new
  TestBlockedFlagsRefusesEveryListingFilter pins blockedFlagFilterFlags
  to the flags blockedCmd registers, in both directions. Every
  registered flag except --flags and --raw must be refused, and every
  entry must name a registered flag. The test walks Flags() rather than
  LocalFlags(), so it does not merge the root's persistent flags into
  blockedCmd, and it skips inherited root flags and cobra's --help.
  Mutants:
  - four fail it: a new filter flag left off the list, a dropped
    entry, a misspelled entry, and --raw added to the list;
  - a simulated earlier in-process run (merged root flags plus --help)
    stays green, and fails once either skip is removed.
- nit (the remote branch's span): the remote BlockedLister comment now
  says why that lister is not wrapped again. The inner lister already
  carries telemetry's span, so wrapping would nest a second span of the
  same name. The comment also says what runs outside that span.
- nit (duplicated order comparator): left as is. finishBlockedIssues
  predates this PR, so merging the two sorts would refactor existing
  code with no review pass left after this one.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Agent-Signature: claude-code-claude-opus-5-5-max on behalf of Gas City Adopt-PR

---------

Co-authored-by: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Co-authored-by: Eddie the Engineer <338826946+gascity-eddie[bot]@users.noreply.github.com>
2026-10-17 12:29:13 +00:00

954 lines
46 KiB
Go

package main
import (
"context"
"errors"
"fmt"
"io"
"os"
"time"
"github.com/spf13/cobra"
"github.com/steveyegge/beads/internal/configfile"
"github.com/steveyegge/beads/internal/eventsjournal"
"github.com/steveyegge/beads/internal/httpapi"
"github.com/steveyegge/beads/internal/storage"
"github.com/steveyegge/beads/internal/storage/backends"
"github.com/steveyegge/beads/internal/storage/contextinfo"
"github.com/steveyegge/beads/internal/storage/domain"
"github.com/steveyegge/beads/internal/storage/externaldeps"
"github.com/steveyegge/beads/internal/storage/uow"
"github.com/steveyegge/beads/issueops"
"github.com/steveyegge/beads/memoryops"
)
// serveCmdName is the command name, shared with the root command's post-run
// policy (runsPostCommandMaintenance) so the exclusion cannot drift from the
// command it names.
const serveCmdName = "serve"
// providerCloseTimeout bounds the shutdown close of a provider serve built
// itself. It is not the drain budget — the server has already drained by then.
const providerCloseTimeout = 10 * time.Second
// serveTokenFileEnv is the environment fallback for --auth-token-file, which an
// operator would otherwise have to thread through a container spec. It follows
// the BEADS_* convention the rest of the binary uses, and applies ONLY when the
// flag was not passed.
//
// It is read here and nowhere else. internal/httpapi never reads the
// environment, so the library, its tests and an embedded caller cannot be
// reconfigured by an exported variable in somebody's shell.
const (
// #nosec G101 -- this is the NAME of an environment variable that holds a
// file PATH. No credential appears in this source file, and none may: a
// token reaches the process only by being read out of that file.
serveTokenFileEnv = "BEADS_SERVE_TOKEN_FILE"
)
var (
serveAddr string
serveAllowNonLoopback bool
serveAuthTokenFile string
serveInsecureNoAuth bool
serveAllowedHosts []string
serveLargeApplyCeiling time.Duration
)
var serveCmd = &cobra.Command{
Use: serveCmdName,
Short: "Serve the beads HTTP API over loopback",
Long: `Serve the beads HTTP API — the same work surface the CLI answers, for
automation clients that would otherwise fork a bd subprocess per call.
The wire contract is described by an OpenAPI document (/v0); GET
/v0/beads/context reports which operations this build actually implements.
DEPLOYMENT
Pass an explicit port. The default 127.0.0.1:0 takes an ephemeral one, which
is right for ad-hoc and test use — where the bound address printed on stdout
is read immediately — but carries no mutual exclusion: two serves against one
workspace then run side by side on different ports with no way to enumerate
them. On a fixed port the second one fails to bind, which is the intended
behavior. Concurrent serves are data-safe either way; claims are arbitrated
in the SQL server.
Run it under a supervisor. bd shuts down gracefully on SIGHUP as well as
SIGINT and SIGTERM, so closing the terminal of a foreground bd serve stops it.
PROBES
GET /healthz is LIVENESS only: it answers from the process and never touches
the database, so it stays green while the database is unreachable. For
readiness use GET /v0/beads/ready?limit=1 — a real query, where 200 means
ready and 503 means live but not ready.
AUTHENTICATION
Optional, and off by default on loopback — where the trust model is the
loopback boundary itself, the same one the database behind it already relies
on. --auth-token-file turns it on: every operation except GET /healthz then
requires an "Authorization: Bearer <token>" header, GET /v0/beads/context
included, because it reports the repo root, beads directory and database name.
The file holds ONE TOKEN PER LINE and every line is accepted. That is the
rotation mechanism: write the new token alongside the old, roll the clients
over, then delete the old line. The file is re-read while the server runs, so
both the addition and the removal take effect within about a second and
neither needs a restart. Write it atomically (a temp file plus rename; a
Kubernetes secret mount already does this).
There is deliberately no --auth-token flag. A credential passed as an
argument is readable by every local user in the process listing.
--allow-non-loopback REQUIRES a token file. Beyond loopback, reaching the
address would otherwise be the whole authorization: any peer could read every
issue and claim work as any actor. --insecure-no-auth is the explicit,
auditable way to say you meant that anyway.
The Host allowlist is what a service deployment usually trips over first. The
DNS-rebinding check answers only to loopback spellings and the bind address,
so a client dialing a service name gets 400 on every request; enumerate the
names it dials with --allowed-host (repeatable). Matching is exact — no
wildcards — and the startup log line prints the effective allowlist.
WHAT THIS DOES NOT DO
No TLS. Even with a token, the credential and every issue body travel in
plaintext, so a deployment beyond loopback has to supply confidentiality
itself — a service mesh, or a network boundary you already trust.
Hooks do not fire. A hook is a user-controlled subprocess per mutation: in a
concurrent server that is an unbounded latency multiplier and an orphaned
child at shutdown, and its working-directory-derived hook lookup is
meaningless in a server process. A CLI claim runs on_update; an HTTP claim
does not.
The per-command auto-commit machinery does not run. Durability is per request:
a successful claim commits inside its own transaction, exactly as a proxied
CLI claim does today.
An actor on an HTTP request is caller-asserted provenance for the audit trail,
not authenticated identity — the same thing it has always been on the CLI,
where any local process can pass any --actor.
It does not run under --readonly, and refuses to start rather than binding.
Every server it binds publishes the issue-claim operation, and the capability
set it advertises is a property of the build rather than of the flags on the
process that started it — so a read-only server would advertise a write it
could never land.
DESTRUCTIVE OPERATIONS
POST /v0/beads/issues:sweep deletes closed beads in bulk — the operation
behind bd purge and bd prune — and nothing it deletes comes back. It shares
the library surface those commands call, so it inherits their guards: pinned
beads are never swept, and a durable sweep with neither a cutoff nor an id
pattern is refused rather than clearing every closed bead in the workspace.
Combined with the trust model above, that means anyone who can reach this
address can erase closed work; bind it accordingly.`,
Args: cobra.NoArgs,
RunE: func(cmd *cobra.Command, args []string) error {
return runServe()
},
}
func init() {
registerServeFlags(serveCmd)
rootCmd.AddCommand(serveCmd)
}
// registerServeFlags declares bd serve's own flags.
//
// It is a named function rather than a block in init so a test that runs the
// command in-process can put the flag set back the way it found it: cobra
// merges every inherited persistent flag into a command's own FlagSet the first
// time it parses one, and that mutation outlives the run.
func registerServeFlags(cmd *cobra.Command) {
cmd.Flags().StringVar(&serveAddr, "addr", "127.0.0.1:0",
"Address to bind as IP:PORT; the host must be a numeric IP literal, and port 0 takes an ephemeral port")
cmd.Flags().BoolVar(&serveAllowNonLoopback, "allow-non-loopback", false,
"Permit a bind beyond loopback. Requires --auth-token-file, since reaching the address would otherwise be the whole authorization")
cmd.Flags().StringVar(&serveAuthTokenFile, "auth-token-file", "",
"Require an Authorization: Bearer token from this file, one token per line, all accepted. Re-read while running, so rewriting it rotates tokens without a restart (env "+serveTokenFileEnv+")")
cmd.Flags().BoolVar(&serveInsecureNoAuth, "insecure-no-auth", false,
"Serve a non-loopback bind with NO authentication. Every peer that can reach the address gets full read and claim access")
cmd.Flags().StringArrayVar(&serveAllowedHosts, "allowed-host", nil,
"Additional Host header value to answer to, e.g. a service DNS name. Repeatable; matched exactly, with no wildcards")
cmd.Flags().DurationVar(&serveLargeApplyCeiling, "large-apply-ceiling", httpapi.DefaultLargeApplyCeiling,
"Whole-run budget for a POST issues:batchApply request over 100 items (a ceiling, not a target; requests at or under 100 items are unaffected). Must be positive. The orchestrator's stop grace must be at least this long plus 5s, or an external SIGKILL can cut off an in-flight large apply a graceful drain would otherwise have waited out; see engdocs/SERVE_RUNBOOK.md")
}
// serveOptions is the part of a server's configuration that depends on NEITHER
// the workspace nor its database source: the operator's flags, and the
// environment fallbacks behind them.
//
// It is deliberately not an httpapi.Config. Every Config bd builds names the
// one database source it serves from, and that source is not known until the
// workspace has been classified — so a Config filled in this early would be a
// server configuration that cannot yet describe a server. The field names match
// Config's because they become those fields verbatim, in applyTo.
type serveOptions struct {
Addr string
AllowNonLoopback bool
InsecureNoAuth bool
AllowedHosts []string
Auth *httpapi.TokenFileAuth
LargeApplyCeiling time.Duration
}
// applyTo writes the operator's choices onto the configuration a database arm
// built. It is the ONLY place they are set, so an arm can add a source but can
// never be the one that forgot the credential or the host allowlist.
func (o serveOptions) applyTo(cfg *httpapi.Config) {
cfg.Addr = o.Addr
cfg.AllowNonLoopback = o.AllowNonLoopback
cfg.InsecureNoAuth = o.InsecureNoAuth
cfg.AllowedHosts = o.AllowedHosts
cfg.Auth = o.Auth
cfg.LargeApplyCeiling = o.LargeApplyCeiling
}
// resolveServeConfig turns the flags and their environment fallbacks into the
// parts of the server configuration that depend on NEITHER the workspace nor a
// listener.
//
// It is separate from runServe, and runs first, for the reason every other
// validation in this command does: a refusal for a posture that cannot be
// served must not depend on which workspace the operator happened to be
// standing in, and must not arrive after a database has been opened.
func resolveServeConfig() (serveOptions, error) {
cfg := serveOptions{
Addr: serveAddr,
AllowNonLoopback: serveAllowNonLoopback,
InsecureNoAuth: serveInsecureNoAuth,
AllowedHosts: serveAllowedHosts,
LargeApplyCeiling: serveLargeApplyCeiling,
}
if _, err := httpapi.ValidateBindAddr(serveAddr, serveAllowNonLoopback); err != nil {
return cfg, err
}
if serveLargeApplyCeiling <= 0 {
return cfg, fmt.Errorf("--large-apply-ceiling must be positive, got %s", serveLargeApplyCeiling)
}
tokenFile := serveAuthTokenFile
if tokenFile == "" {
tokenFile = os.Getenv(serveTokenFileEnv)
}
if err := httpapi.ValidateAuthPosture(serveAllowNonLoopback, tokenFile != "", serveInsecureNoAuth); err != nil {
return cfg, err
}
if tokenFile != "" {
auth, err := httpapi.NewTokenFileAuth(tokenFile)
if err != nil {
return cfg, fmt.Errorf("--auth-token-file: %w", err)
}
cfg.Auth = auth
}
for _, host := range serveAllowedHosts {
if err := httpapi.ValidateAllowedHost(host); err != nil {
return cfg, err
}
}
return cfg, nil
}
func runServe() error {
// Flag validation first: it depends on nothing about the workspace, so the
// refusal for a bad --addr or an unservable auth posture is the same in
// every mode, and it lands before anything opens a database.
opts, err := resolveServeConfig()
if err != nil {
return HandleError("%v", err)
}
if readonlyMode {
return HandleError("%v", errServeReadonly())
}
cwd, err := os.Getwd()
if err != nil {
return HandleError("cannot resolve working directory: %v", err)
}
info, err := contextinfo.NewContextProvider(cwd, Version).ContextUseCase().GetContextInfo(rootCtx)
if err != nil {
return HandleError("cannot resolve workspace context: %v", err)
}
// The classification reads the workspace's own configuration, so it runs
// after the context resolves rather than before it. A directory with no
// workspace at all therefore reports that it has none, instead of reporting
// the embedded refusal for a workspace nobody found.
db, err := serveDatabaseSource(info.BeadsDir)
if err != nil {
return HandleError("%v", err)
}
if db.source == serveSourceStore {
// Nothing to create. PersistentPreRunE already opened this workspace
// through the same backends.Lookup dispatch every ordinary bd command
// opens it with, so the store bd list and bd create answer from is the
// store sitting in front of this server — one creation path, which is
// the whole point of this arm. Opening a second handle here would
// double the pools and self-conflict with any backend that takes an
// exclusive workspace lock.
//
// Closing it is the root command's business too: PersistentPostRunE
// runs after this function returns, which is after the server has
// fully drained, so no request can reach a closed store. runServe must
// not close it.
journalEnabled := eventsjournal.EnabledFor(info.BeadsDir)
roles, err := serveIssueRoles(store, journalEnabled)
if err != nil {
return HandleError("bd serve: %v", err)
}
defer startServeEventsJournalMaintenance(info.BeadsDir, store)()
return serveListen(opts, httpapi.Config{
Reader: roles.reader,
Claimer: roles.claimer,
BatchCloser: roles.batchCloser,
ReadyClaimer: roles.readyClaimer,
Releaser: roles.releaser,
Lifecycle: roles.lifecycle,
Settings: roles.settings,
Stats: roles.stats,
CycleDetector: roles.cycles,
EdgeReader: roles.edges,
GraphCounter: roles.edgeCounter,
BatchGetter: roles.batchGetter,
LeaseReclaimer: roles.leaseReclaimer,
Heartbeater: roles.heartbeater,
BlockedLister: roles.blockedLister,
Relations: roles.relations,
Commenter: roles.commenter,
BlockingAnnotator: roles.blocking,
TreeWalker: roles.tree,
ReadyCounter: roles.readyCounter,
Counter: roles.counter,
Querier: roles.querier,
Sweeper: roles.sweeper,
Deleter: roles.deleter,
BatchCreator: roles.batchCreator,
DependencyEditor: roles.dependencyEditor,
MetadataCAS: roles.metadataCAS,
BatchApplier: roles.batchApplier,
Memories: roles.memories,
// Nil when this backend has no journal seam and the workspace never
// asked for one; Listen requires it exactly when the flag below is
// set, and serveIssueRoles has already refused the enabled case.
EventsJournal: roles.eventsJournal,
// GET /v0/beads/events refuses outright on a workspace that records
// nothing, because a disabled journal and an empty one are one
// answer at the data level. Resolved ONCE above, so the role
// extraction, this flag and the maintenance ticker cannot disagree
// about whether this workspace journals.
EventsJournalEnabled: journalEnabled,
// The roles above come from the storage chain, which interposes
// the external-dependency policy (wireStorageDecorators); the
// handshake advertises it only if that layer is really there.
ExternalDependencyPolicy: externaldeps.Applied(store),
Workspace: info,
SchemaVersion: JSONSchemaVersion,
Mode: serveResolvedMode(info, db),
})
}
// Serve from the provider BENEATH the hook layer. `bd serve` documents that
// it runs no hooks — a user-controlled subprocess per mutation is an
// unbounded latency multiplier and an orphaned child at shutdown — while
// proxied mode wires a notifying provider so the CLI's own writes keep
// firing them. This is the unit-of-work twin of the
// (*storage.HookFiringStore).Unwrap the store-shaped source takes.
provider := uow.UnwrapProvider(uowProvider)
if provider != nil {
// Remove hooks, then restore the external-dependency policy. The policy
// is not a hook and must remain on every served ready/claim path.
provider = wireExternalDependencyUOWProvider(provider)
}
if provider == nil {
// Server, external-server and shared-server workspaces: PersistentPreRunE
// builds a DoltStore for those and no unit-of-work provider, so serve
// builds its own from the same connection settings the store used.
//
// On this arm that store stays open for the life of the process and
// serve never touches it. It is not free either: its pool holds an idle
// connection or two against the very server this process is about to
// pool twenty more on. Worth knowing when sizing a shared Dolt server's
// max_connections.
topology, err := resolveServerModeUOWTopology(rootCtx, info.BeadsDir)
if err != nil {
return HandleError("bd serve: %v", err)
}
// GET /v0/beads/context is the one endpoint automation is told to trust
// for this server's identity, and its Database comes from metadata.json,
// which knows nothing about --global. Report the database the provider
// actually opened, or the handshake names one database while every
// operation answers from another.
//
// The store source needs no such override: backend.Open consumes the
// same metadata.json GetContextInfo just read, so the handshake and the
// operations share one source of truth by construction.
info.Database = topology.database
p, err := newSQLServerUOWProvider(rootCtx, info.BeadsDir, topology)
if err != nil {
// A daemon has no operator watching a prompt, so a migration-gate
// refusal here must fail startup loudly and completely: the whole
// block, in the service log, naming the one-time `bd migrate
// schema` that unblocks it. No prompt, no auto-consent, no
// half-started daemon serving a schema it refused to reconcile.
if rendered := renderTypedOpenError(err); rendered {
return SilentExit()
}
return HandleError("bd serve: %v", err)
}
defer func() {
// By the time this runs the signal context is already canceled, so a
// close that inherited it could not do any of its work.
closeCtx, cancel := context.WithTimeout(context.WithoutCancel(rootCtx), providerCloseTimeout)
defer cancel()
if err := p.Close(closeCtx); err != nil {
fmt.Fprintf(os.Stderr, "bd serve: closing the unit-of-work provider: %v\n", err)
}
}()
provider = wireExternalDependencyUOWProvider(p)
}
defer startServeEventsJournalMaintenance(info.BeadsDir, provider)()
return serveListen(opts, httpapi.Config{
Provider: provider,
// No EventsJournal field on this arm: the provider carries the journal
// read as one of its own capability accessors, exactly as it carries
// every other role Listen would otherwise need spelled out. Activation
// is still the workspace's answer and still has to be handed in — the
// provider knows how to READ the journal, not whether this workspace has
// one.
EventsJournalEnabled: eventsjournal.EnabledFor(info.BeadsDir),
ExternalDependencyPolicy: externaldeps.AppliedToProvider(provider),
Workspace: info,
SchemaVersion: JSONSchemaVersion,
Mode: serveResolvedMode(info, db),
})
}
// startServeEventsJournalMaintenance runs events-journal retention for the life
// of the server and returns the function that stops it.
//
// A server is not a command, so it is excluded from the per-command maintenance
// net (runsPostCommandMaintenance) — including the writer-pays auto-prune
// trigger that fires after a CLI mutation. Without this, the one topology that
// journals fastest, because it is the one accepting concurrent HTTP mutations
// for hours, would be the one that never prunes. A ticker is the honest shape
// for a process with no command boundary: it polls, and the same persisted
// watermark every CLI process reads decides whether a pass is actually due, so
// a server and the CLIs beside it share one schedule rather than three.
//
// The stop is deferred by the caller so it runs after the server has drained:
// maintenance and requests overlap freely (both are ordinary transactions), but
// nothing should still be deleting when the provider closes underneath it.
func startServeEventsJournalMaintenance(beadsDir string, source any) func() {
if !eventsjournal.EnabledFor(beadsDir) || !eventsjournal.AutoPruneEnabledFor(beadsDir) {
return func() {}
}
// The plumbing this server answers FROM, not whatever the root pre-run left
// in a global: on the server-mode arm serve builds its own provider, and
// maintaining a journal through a different handle than the one writing it
// is how a topology ends up pruning the wrong database.
runner := eventsJournalMaintenanceRunnerFor(source)
if runner == nil {
return func() {}
}
return eventsjournal.StartAutoPruneTicker(rootCtx, runner,
eventsjournal.DefaultAutoPruneTickInterval,
eventsJournalAutoPruneOptions(),
reportEventsJournalAutoPrune)
}
// serveListen binds and runs. It is where the two database sources converge:
// everything past the source is the same server.
//
// The operator's options and the database source arrive separately because they
// are resolved at different times — the flags before anything opens a database,
// the source only once the workspace has been classified — and this is where
// they meet, once, for every arm.
//
// Graceful shutdown rides the signal context the root command already sets up
// (SIGINT/SIGTERM/SIGHUP). A proxied provider is closed where every proxied
// command closes it, in PersistentPostRunE — which in proxied mode does nothing
// else; the provider serve built for a server-mode workspace is closed by
// runServe's own defer, and a registered backend's store by the same
// PersistentPostRunE that opened it. None of those paths runs the auto-commit,
// export or push maintenance: proxied mode never had it, and serve is excluded
// from it by name (runsPostCommandMaintenance, cmd/bd/main.go).
func serveListen(opts serveOptions, cfg httpapi.Config) error {
opts.applyTo(&cfg)
// The posture warning belongs here rather than on either source arm: it
// reports what this bind does not protect, which is a property of the
// listener both arms share.
warnServePosture(os.Stderr, opts)
srv, err := httpapi.Listen(cfg)
if err != nil {
return HandleError("%v", err)
}
return srv.Serve(rootCtx)
}
// warnServePosture says out loud what this deployment does not protect.
//
// Two different warnings, because they are two different exposures. Running
// unauthenticated beyond loopback is the one that was always here, and the
// operator now has to have asked for it by name. Running authenticated beyond
// loopback is the remaining gap: the token itself crosses the network in
// plaintext on every request, so a network that can read it can replay it.
//
// Nothing is printed for the loopback default, which is what it has always
// been.
func warnServePosture(w io.Writer, opts serveOptions) {
if !opts.AllowNonLoopback {
return
}
if opts.Auth == nil {
fmt.Fprintf(w,
"bd serve: WARNING: --insecure-no-auth binds %s beyond loopback with no authentication. "+
"Any peer that can reach it can read every issue and claim work as any actor.\n",
opts.Addr)
return
}
fmt.Fprintf(w,
"bd serve: WARNING: %s is bound beyond loopback with bearer authentication but NO TLS. "+
"Tokens and issue data travel in plaintext; deploy it inside a trusted network boundary.\n",
opts.Addr)
}
// serveSource names which of httpapi.Config's two database sources a workspace
// is served from.
type serveSource int
const (
// serveSourceProvider is the unit-of-work provider: one unit of work per
// request, timed into that request's uow_ms and drawn from a pool bd serve
// bounds itself. Every Dolt SQL-server topology takes it.
serveSourceProvider serveSource = iota
// serveSourceStore is the role set, taken off the store the root command
// already opened. A registered backend's facade is a store rather than a
// unit-of-work provider, so this is the source it has.
serveSourceStore
)
// String names the source. It exists so a failed comparison prints "store" or
// "provider" rather than an integer.
func (s serveSource) String() string {
if s == serveSourceStore {
return "store"
}
return "provider"
}
// serveDatabase is the resolved answer to the one question bd serve asks about
// a workspace before it binds anything: where does this server read and claim
// from.
type serveDatabase struct {
// source is which of httpapi.Config's two database sources to build.
source serveSource
// backend is the registered backend's name on the store source, and empty
// on the provider source.
backend string
}
// serveDatabaseSource classifies the workspace. It is both the mode gate and
// the wiring decision, in one function, so the two can never disagree about one
// workspace.
//
// THE REGISTRY IS CONSULTED FIRST, and that ordering is not a preference.
// PersistentPreRunE dispatches the store open on backends.Lookup before
// anything looks at Dolt mode, so a registered workspace opens its registered
// store even with BEADS_DOLT_SHARED_SERVER=1 exported. Resolving it the other
// way here would build a Dolt unit-of-work provider over a non-Dolt store and
// answer HTTP from a different database than the CLI reaches in the same
// directory. Registry-first is also what closes the !cgo corner, where
// isEmbeddedMode is a constant false and a registered workspace would otherwise
// be handed to the Dolt provider and fail with a misleading Dolt error — or
// connect to a defaulted host and serve the wrong database.
//
// EMBEDDED DOLT IS PERMANENT, and this is the only place that refusal lives.
// Its commit protocol runs outside the SQL transaction on a separate
// connection, so the per-request atomicity this server's contract states would
// be a lie there. That is a property of the backend rather than of what has
// been built so far, which is also why no unit-of-work provider for it exists
// or will. Nothing downstream will catch a bypass: internal/httpapi cannot see
// the backend behind a role, and every store publishes every role accessor
// whatever it is. TestServeNamesOneDatabaseSourcePerServerItBuilds pins that
// the roles are only ever reached through here.
func serveDatabaseSource(beadsDir string) (serveDatabase, error) {
cfg, err := configfile.Load(beadsDir)
if err != nil {
// Never classify past an unreadable metadata.json. The classification's
// default is the embedded refusal, so falling back would refuse a
// workspace whose real backend nobody managed to read.
return serveDatabase{}, fmt.Errorf("load %s: %w", configfile.ConfigPath(beadsDir), err)
}
if backend := normalizeLoadedConfig(cfg).GetBackend(); backends.Registered(backend) {
return serveDatabase{source: serveSourceStore, backend: backend}, nil
}
if isEmbeddedMode() {
return serveDatabase{}, errServeEmbedded()
}
return serveDatabase{source: serveSourceProvider}, nil
}
// errServeReadonly refuses `bd --readonly serve`.
//
// AHEAD OF THE WORKSPACE, deliberately: every server this command builds
// publishes the same operation set, claim included, so the answer cannot depend
// on which database source the workspace resolves to. Putting it here is also
// what makes it one answer rather than two — the two sources degraded
// differently, and both silently.
//
// - On the STORE source the root command opens the workspace through
// backend.OpenReadOnly and serve takes its claimer off that store. The
// server bound, GET /v0/beads/context went on advertising `issues.claim`
// (the capability set is derived from the route table and knows nothing
// about a CLI flag), and every claim answered 500 with the issue left open.
// - On the PROVIDER source serve builds its own unit-of-work provider from
// the workspace's connection settings, which carries no read-only posture,
// so `--readonly` bought the operator nothing and every claim landed.
// (Proxied mode never got here: the root pre-run already refuses strict
// readonly for it.)
//
// REFUSING RATHER THAN NARROWING THE SURFACE. Dropping `issues.claim` from a
// read-only server's advertised capabilities would be a wire change — that list
// is the documented pre-flight a client checks — and it would make one
// operation's presence depend on a flag on the process that happened to start
// the server, which no client can discover before connecting. bd already
// answers this question the same way one layer down, where a backend that
// cannot guarantee mutation-free access is turned away rather than opened
// anyway (the proxy.readonly.unsupported refusal in cmd/bd/main.go).
//
// The value is read from the global rather than a flag lookup because
// `readonly` is also a config key, and PersistentPreRunE has already folded
// both into readonlyMode by the time any RunE runs.
func errServeReadonly() error {
return errors.New("bd serve is unavailable under strict readonly (--readonly, or readonly in config): " +
"every server it binds publishes the issue-claim operation, and refusing to start is the only honest " +
"answer — a server that advertised a claim it could never land would be worse than no server")
}
// errServeEmbedded is the PERMANENT refusal. The message says what the
// workspace is and what serve needs, and promises nothing further: the reason
// is the embedded backend's commit protocol (see serveDatabaseSource), which no
// amount of provider or role plumbing changes.
//
// The mode belongs in the message, not in ErrUnsupported.Backend: that field is
// documented as a BACKEND name and is the embryo of the pluggable-backend error
// taxonomy, so putting a topology string in it would hand every downstream
// errors.As a mixed backend/mode vocabulary.
func errServeEmbedded() error {
return fmt.Errorf("%w: bd serve requires a Dolt SQL server; this workspace uses embedded Dolt",
&storage.ErrUnsupported{Op: "serve", Backend: "embedded-dolt"})
}
// serveRoleSource is the surface serveIssueRoles reaches on the store, spelled
// out rather than taken as a whole storage.DoltStorage.
//
// THE POINT IS THE TEST STUBS. A stub that stands in for a store has to satisfy
// whatever this function asks for, and the only affordable way to satisfy a
// hundred-method interface is to embed it and leave it nil — which answers every
// accessor the stub forgot with a promoted method on a nil interface. That is a
// segfault inside the loop below rather than a compile error, and it has landed
// twice: once on GraphCounter in serve_source_test.go, and once on the same role
// in serve_store_identity_test.go, where no local -run pattern named the test
// and only a full-package CI shard found it.
//
// Named narrowly, a stub can DECLARE this set and assert it, so the next role
// added to the loop below is a build failure in the file that has to grow a
// method — with the method's name in the error.
//
// A whole store is one of these, which is what the assertion beneath it pins:
// the production call site passes exactly what it always did.
type serveRoleSource interface {
IssueReader() (issueops.Reader, error)
IssueClaimer() (issueops.Claimer, error)
BatchCloser() (issueops.BatchCloser, error)
ReadyClaimer() (issueops.ReadyClaimer, error)
Releaser() (issueops.Releaser, error)
IssueLifecycle() (issueops.Lifecycle, error)
WorkspaceConfig() (issueops.WorkspaceConfig, error)
StatsReporter() (issueops.StatsReporter, error)
CycleDetector() (issueops.CycleDetector, error)
EdgeReader() (issueops.EdgeReader, error)
GraphCounter() (issueops.GraphCounter, error)
BatchGetter() (issueops.BatchGetter, error)
LeaseReclaimer() (issueops.LeaseReclaimer, error)
Heartbeater() (issueops.Heartbeater, error)
BlockedLister() (issueops.BlockedLister, error)
IssueRelations() (issueops.Relations, error)
Commenter() (issueops.Commenter, error)
BlockingAnnotator() (issueops.BlockingAnnotator, error)
TreeWalker() (issueops.TreeWalker, error)
ReadyCounter() (issueops.ReadyCounter, error)
Counter() (issueops.Counter, error)
Querier() (issueops.Querier, error)
Sweeper() (issueops.Sweeper, error)
Deleter() (issueops.Deleter, error)
BatchCreator() (issueops.BatchCreator, error)
DependencyEditor() (issueops.DependencyEditor, error)
MetadataCAS() (issueops.MetadataCAS, error)
BatchApplier() (issueops.BatchApplier, error)
Memories() (memoryops.Memories, error)
}
var _ serveRoleSource = storage.DoltStorage(nil)
// serveIssueRoles takes the roles this server answers from off the store the
// root command already opened.
//
// ONE PEEL, and never storage.UnwrapStore. bd's chain is
// HookFiringStore -> InstrumentedStorage -> raw, and every decorator publishes
// its own roles — that is what the accessors are for — so store.IssueClaimer()
// returns a claimer that runs the workspace's on_update script for every claim
// it lands. This server documents that hooks do not fire, so the hook layer has
// to come off; the telemetry layer beneath it must not, or every request this
// process serves goes unspanned and untimed. httpapi.Listen refuses a
// hook-firing role rather than trusting this comment, so getting it wrong is a
// startup error rather than a silent subprocess per claim.
//
// The assertion is conditional because a BD_NO_HOOKS=1 workspace has no hook
// layer to peel.
//
// It returns the WHOLE set httpapi.Config requires; Listen refuses a partial
// set (see checkDatabaseSource), so a role missing here is a startup failure
// rather than a nil dereference on the first request that reaches it.
func serveIssueRoles(src serveRoleSource, journalEnabled bool) (serveRoles, error) {
var roles serveRoles
if src == nil {
// A set of nil roles would reach Listen as "no database source" —
// true, and useless. Name the condition that actually happened.
return roles, errors.New("no store is open for this workspace")
}
if hooked, ok := src.(*storage.HookFiringStore); ok {
src = hooked.Unwrap()
}
// Each entry binds one Config field to the accessor that fills it, and
// names itself in the failure.
type binding struct {
name string
get func() error
}
for _, b := range []binding{
{"issue reader", func() (err error) { roles.reader, err = src.IssueReader(); return }},
{"issue claimer", func() (err error) { roles.claimer, err = src.IssueClaimer(); return }},
{"batch closer", func() (err error) { roles.batchCloser, err = src.BatchCloser(); return }},
{"ready claimer", func() (err error) { roles.readyClaimer, err = src.ReadyClaimer(); return }},
{"issue releaser", func() (err error) { roles.releaser, err = src.Releaser(); return }},
{"issue lifecycle", func() (err error) { roles.lifecycle, err = src.IssueLifecycle(); return }},
{"workspace config", func() (err error) { roles.settings, err = src.WorkspaceConfig(); return }},
{"stats reporter", func() (err error) { roles.stats, err = src.StatsReporter(); return }},
{"cycle detector", func() (err error) { roles.cycles, err = src.CycleDetector(); return }},
{"edge reader", func() (err error) { roles.edges, err = src.EdgeReader(); return }},
{"graph counter", func() (err error) { roles.edgeCounter, err = src.GraphCounter(); return }},
{"batch getter", func() (err error) { roles.batchGetter, err = src.BatchGetter(); return }},
{"lease reclaimer", func() (err error) { roles.leaseReclaimer, err = src.LeaseReclaimer(); return }},
{"heartbeater", func() (err error) { roles.heartbeater, err = src.Heartbeater(); return }},
{"blocked lister", func() (err error) { roles.blockedLister, err = src.BlockedLister(); return }},
{"issue relations", func() (err error) { roles.relations, err = src.IssueRelations(); return }},
{"commenter", func() (err error) { roles.commenter, err = src.Commenter(); return }},
{"blocking annotator", func() (err error) { roles.blocking, err = src.BlockingAnnotator(); return }},
{"tree walker", func() (err error) { roles.tree, err = src.TreeWalker(); return }},
{"ready counter", func() (err error) { roles.readyCounter, err = src.ReadyCounter(); return }},
{"counter", func() (err error) { roles.counter, err = src.Counter(); return }},
{"querier", func() (err error) { roles.querier, err = src.Querier(); return }},
{"sweeper", func() (err error) { roles.sweeper, err = src.Sweeper(); return }},
{"deleter", func() (err error) { roles.deleter, err = src.Deleter(); return }},
{"batch creator", func() (err error) { roles.batchCreator, err = src.BatchCreator(); return }},
{"dependency editor", func() (err error) { roles.dependencyEditor, err = src.DependencyEditor(); return }},
{"metadata cas", func() (err error) { roles.metadataCAS, err = src.MetadataCAS(); return }},
{"batch applier", func() (err error) { roles.batchApplier, err = src.BatchApplier(); return }},
{"memories", func() (err error) { roles.memories, err = src.Memories(); return }},
{"events journal", func() error {
// storage.UnwrapStore rather than the ONE peel above, and that is not
// an exception to this function's rule — it is the rule applied to a
// capability that no decorator publishes. The hook and telemetry
// layers wrap ROLES; neither implements the journal seam, so the
// assertion has to reach the concrete store or it finds nothing at
// all. Nothing is skipped by going the whole way: there is no
// journal decorator to peel past.
//
// A ROLE REACHED BY ASSERTION IS NOT A ROLE OUTSIDE THE RULES.
// journalops.Journal is a facade role with a contract tier and a
// per-leg lock like every other; what it has no accessor for is
// the reason issueops.Importer has none either — the capability is
// not on storage.DoltStorage's published surface, so the census
// that would otherwise miss it reads SOURCE rather than reflecting
// over accessors (backend/conformance/role_coverage_scan_test.go).
// The assertion below is what a front door does with such a role,
// not a shortcut around one.
cursor, ok := serveJournalCursor(src)
if ok {
roles.eventsJournal = cursor
return nil
}
// A backend that cannot read the journal is an ordinary backend
// while the workspace records nothing — the journal is off by
// default, and eventsjournal.Apply takes exactly this deal when it
// binds activation at open time. Only an ENABLED workspace has
// asked for something this backend cannot do, and the message is
// the one `bd events` prints for the same condition.
if journalEnabled {
return fmt.Errorf("storage backend does not support the events journal")
}
return nil
}},
} {
if err := b.get(); err != nil {
return serveRoles{}, fmt.Errorf("%s: %w", b.name, err)
}
}
return roles, nil
}
// serveJournalCursor is storage.UnwrapStore reached from serveRoleSource, which
// is narrower than the whole store UnwrapStore takes. A source that is not a
// store has no decorator to peel — the test stubs are exactly that — so it is
// asked for the seam as it stands.
//
// It survives the journal's promotion to a facade role (journalops.Journal,
// which storage.EventsJournalCursor aliases) unchanged, and deliberately: a
// role with no accessor is reached exactly this way. issueops.Importer set the
// precedent — one accessor, none on the store interface — and the apparatus
// that keeps such a role honest is the conformance census, which parses the
// facade packages for declarations instead of reflecting over the accessors a
// store hands out. There is no accessor for this function to have been
// replaced by.
func serveJournalCursor(src serveRoleSource) (storage.EventsJournalCursor, bool) {
raw := any(src)
if store, ok := src.(storage.DoltStorage); ok {
raw = storage.UnwrapStore(store)
}
cursor, ok := raw.(storage.EventsJournalCursor)
return cursor, ok
}
// serveRoles is the store-shaped database source, assembled once before Listen.
// It is deliberately NOT an httpapi.Config: the gate test in serve_test.go
// requires every httpapi.Config literal in this package to sit in a function
// that consulted serveDatabaseSource.
type serveRoles struct {
reader issueops.Reader
claimer issueops.Claimer
// batchCloser closes many issues as one transaction, behind
// POST /v0/beads/issues:batchClose. Its accessor does NOT recurse through
// the hook decorator today, so it is taken off the peeled store with the
// rest for uniformity rather than out of necessity.
batchCloser issueops.BatchCloser
// readyClaimer is the atomic take of ready work, behind
// POST /v0/beads/issues:claimNext. Its accessor does NOT recurse through
// the hook decorator today, so it is taken off the peeled store with the
// rest for uniformity rather than out of necessity.
readyClaimer issueops.ReadyClaimer
// releaser is the claim's inverse, behind
// POST /v0/beads/issues/{id}:release. Its accessor recurses through the
// hook decorator like the two below it — a release is an update, so
// HookFiringStore.Releaser fires the workspace's on_update script — which
// is why it comes off the PEELED store with the rest.
releaser issueops.Releaser
lifecycle issueops.Lifecycle
settings issueops.WorkspaceConfig
stats issueops.StatsReporter
cycles issueops.CycleDetector
edges issueops.EdgeReader
edgeCounter issueops.GraphCounter
// batchGetter is the one-snapshot, many-ids read behind
// POST /v0/beads/issues:batchGet. Its hook decorator recurses to the inner
// getter WITHOUT wrapping it — a read fires no completion hooks — so it is
// taken off the peeled store with the rest for uniformity rather than out
// of necessity.
batchGetter issueops.BatchGetter
// leaseReclaimer is the stale-lease sweep behind
// POST /v0/beads/issues:reclaim. Its hook decorator WRAPS (a reclaim is an
// update per reverted row), which is why it comes off the peeled store with
// the releaser: bd serve runs no hooks. heartbeater, the lease refresh
// behind POST /v0/beads/issues/{id}:heartbeat, comes off the same store
// for the same reason: its decorator WRAPS too, firing on_update for a
// re-arm (a refresh fires nothing).
leaseReclaimer issueops.LeaseReclaimer
heartbeater issueops.Heartbeater
blockedLister issueops.BlockedLister
relations issueops.Relations
commenter issueops.Commenter
blocking issueops.BlockingAnnotator
tree issueops.TreeWalker
readyCounter issueops.ReadyCounter
counter issueops.Counter
querier issueops.Querier
sweeper issueops.Sweeper
deleter issueops.Deleter
batchCreator issueops.BatchCreator
// dependencyEditor is the second role here whose accessor recurses through
// the hook decorator, so taking it off the peeled store is not optional:
// HookFiringStore.DependencyEditor fires the workspace's update hook per
// edited source issue, and this server documents that hooks do not fire.
dependencyEditor issueops.DependencyEditor
// metadataCAS is the conditional single-key metadata write. Its accessor
// recurses through the hook decorator, so the ONE peel above is what keeps
// this server from running the workspace's on_update script per swap.
metadataCAS issueops.MetadataCAS
// batchApplier is the role that makes the ONE peel above matter most, and
// the arithmetic is what makes it worth its own sentence. Its hook wrapper
// fires FOUR vocabularies from one call — on_create for every created item,
// on_update for every changed update AND once per distinct edge source, and
// the close hooks for every close that landed — so one hundred-item plan
// served from an unpeeled applier is up to a hundred of the workspace's own
// subprocesses spawned inside a single HTTP request, holding a write
// transaction open while they run. Every other role here costs at most one
// per mutation.
batchApplier issueops.BatchApplier
// memories is the one role here that is not an issueops role: the memory
// plane is user data riding in the config table under its own merge class,
// so it has its own leaf package.
memories memoryops.Memories
// eventsJournal is the only role here that comes from a TYPE ASSERTION
// rather than an accessor, because the journal is not part of DoltStorage's
// published surface: it is a replay feed over engine state on a
// dolt_ignored table that the two concrete stores implement and a backend
// may not. Missing it is a startup error rather than a route that 500s,
// which is the same deal every other role here takes.
//
// It IS a role — journalops.Journal, which storage.EventsJournalCursor
// aliases — with its own contract tier and per-leg lock. Accessorless is
// the issueops.Importer shape, not an exemption; see serveJournalCursor.
eventsJournal storage.EventsJournalCursor
}
// serveResolvedMode labels the topology for the startup log line. Cosmetic —
// nothing dispatches on it — but the managed/external distinction is worth
// naming: an external dolt sql-server shares its max_connections budget with
// every other bd process pointed at it, and this server's pool is a claim on
// that budget.
//
// A registered backend is named instead of being given a Dolt mode, which it
// no longer has: GetContextInfo projects the Dolt-derived identity only for the
// Dolt backend (internal/storage/domain/context.go), so info.DoltMode is empty
// here and " (external dolt)" would read as a bare parenthetical about a
// topology this workspace is not on.
func serveResolvedMode(info domain.ContextInfo, db serveDatabase) string {
if db.source == serveSourceStore {
return db.backend + " (registered backend)"
}
if !usesProxiedServer() {
// Server, external-server and shared-server: serve fronts the running
// dolt sql-server rather than starting one, so from this process the
// server is external even when Beads is what started it.
return info.DoltMode + " (external dolt)"
}
client, err := configfile.LoadProxiedServerClientInfo(info.BeadsDir)
if err == nil && client != nil && client.External != nil {
return info.DoltMode + " (external dolt)"
}
return info.DoltMode + " (managed dolt)"
}