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 ¶
This section is empty.
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 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 sends SIGTERM to the processes recorded in the pid files written by Start and removes those pid files. Missing pid files or stale pids are not an error: Stop is idempotent so callers can shut down without first checking whether Start has run.
As a safety, Stop will not signal the calling process. If the recorded pid is the same as 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