Documentation
¶
Overview ¶
Package hub starts and stops the embedded Fossil hub repo and the embedded NATS JetStream server that together form the orchestrator substrate documented in ADR 0023.
The package replaces the previous bash hub-bootstrap.sh / hub-shutdown.sh scripts. Callers no longer need `fossil` or `nats-server` on PATH; the servers run in-process via libfossil and nats-server/v2/server.
Two entry points:
Start(ctx, root, opts...) — idempotent. Creates .bones/ if missing, seeds the hub from git-tracked files on first run, starts both servers, and writes pid files. With WithDetach(true) returns once both servers are accepting connections; otherwise blocks until ctx is canceled. Stop(root) — sends SIGTERM to the pids written by Start and removes the pid files. Idempotent: missing or stale pid files are not an error.
Index ¶
Constants ¶
This section is empty.
Variables ¶
var ErrSeedPrecondition = errors.New(
"no git-tracked files to seed hub fossil from; commit at least one " +
"file (`git add . && git commit -m init`) before running " +
"bones hub start")
ErrSeedPrecondition is returned by Start when the workspace has no git-tracked files for seedHubRepo to commit. Surfaced before the parent spawns the detached child so the user sees the real error (and an actionable next step) without waiting out the TCP-probe readyTimeout. See #138 item 9.
Functions ¶
func FossilURL ¶ added in v0.4.1
FossilURL returns the hub Fossil HTTP URL recorded for the workspace at root, or "" if no hub is currently running there.
Consumers (`bones up`, `swarm join/commit/close`, `tasks status`, etc.) read this rather than hardcoding 127.0.0.1:8765 so two bones workspaces can run concurrently with port allocations of their own.
func HubFossilPath ¶ added in v0.6.0
HubFossilPath returns the on-disk path of the hub fossil for the given workspace root. Use this rather than building the path literally in cli/ so verbs survive future layout changes.
func IsRunning ¶ added in v0.7.1
IsRunning reports whether a hub for the workspace at root is currently running. Returns (pid, true) when both fossil.pid and nats.pid exist and name live processes; (0, false) otherwise.
Read-only. Used by cli/up to print accurate post-scaffold status without spawning anything (per ADR 0041 the hub is started lazily on first verb, not by `bones up`).
func NATSURL ¶ added in v0.4.1
NATSURL returns the hub NATS URL recorded for the workspace at root, or "" if no hub is running.
func Start ¶
Start brings up the orchestrator hub: a Fossil repository at .bones/hub.fossil seeded from git-tracked files, a Fossil HTTP server on the chosen port, and an embedded NATS JetStream server.
Idempotent: if both pid files exist and the recorded processes are alive, Start returns nil immediately.
With WithDetach(true) the calling process fork-execs itself in "foreground" mode, waits for both servers to become reachable, and returns. The child outlives the caller and owns the servers; pid files reference the child. This is what `bones hub start --detach` uses so a shell can fire-and-forget the hub.
Without detach, Start blocks on ctx.Done(): the calling process is the hub. Pid files reference the calling process. On cancellation, both servers shut down cleanly and pid files are removed.
func Stop ¶
Stop terminates the processes recorded in the pid files written by Start and removes those pid files. SIGTERM first; if the process is still alive after stopGrace, SIGKILL. Pid files are only removed once the process is confirmed dead so a follow-up Start cannot mistake an orphan-still-alive for "nothing to clean up" (#138).
Missing pid files or stale pids are not an error: Stop is idempotent so callers can shut down without first checking whether Start ran.
As a safety, Stop will not signal the calling process. If the recorded pid matches os.Getpid(), Stop only removes the pid file. The foreground Start has its own ctx-cancellation path; signaling self would terminate the caller before it could clean up.
Types ¶
type Option ¶
type Option func(*opts)
Option configures Start.
func WithDetach ¶
WithDetach controls Start's blocking behavior. When true, Start returns as soon as both readiness probes succeed; the servers continue running in goroutines until the process exits or Stop is called. When false (the default), Start blocks on ctx.Done() and shuts both servers down cleanly when ctx is canceled.
func WithFossilPort ¶
WithFossilPort pins the Fossil HTTP port. Zero means "let the hub allocate per-workspace" (default behavior).
func WithNATSPort ¶
WithNATSPort pins the NATS client port. Zero means "let the hub allocate per-workspace" (default behavior).
Source Files