Skip to content

Local code intelligence for developers and AI agents. Connect code, docs and infrastructure in a persistent graph, with CBM Lens, MCP tools, agent integrations and change-aware test selection.

12.4 KB
Raw Blame
/*
 * bootstrap.h — Process-role policy and mandatory daemon bootstrap.
 *
 * Role classification must happen before any stateful initialization in
 * main(): no store, watcher, UI, diagnostics, or index supervisor may be
 * constructed until the process is known to be the daemon, one of its
 * internal workers, a thin client, or an explicitly stateless command.
 */
#ifndef CBM_DAEMON_BOOTSTRAP_H
#define CBM_DAEMON_BOOTSTRAP_H

#include "daemon/runtime.h"
#include "daemon/version_cohort.h"

#include <stdbool.h>
#include <stddef.h>
#include <stdint.h>

#define CBM_DAEMON_INTERNAL_ARG "--cbm-daemon-internal"
#define CBM_DAEMON_PERMANENT_ARG "--cbm-daemon-permanent"
#define CBM_DAEMON_BOOTSTRAP_LAUNCH_ARGC 3U

typedef enum {
    CBM_DAEMON_PROCESS_INVALID = 0,
    CBM_DAEMON_PROCESS_STATELESS,
    CBM_DAEMON_PROCESS_DAEMON,
    CBM_DAEMON_PROCESS_WORKER,
    CBM_DAEMON_PROCESS_MCP_CLIENT,
    CBM_DAEMON_PROCESS_LOCAL_CLI,
    CBM_DAEMON_PROCESS_HOOK_CLIENT,
    CBM_DAEMON_PROCESS_DAEMON_CTL,
} cbm_daemon_process_role_t;

/* Pure argv classifier. argv[0] is the executable. The hidden daemon role is
 * accepted only as the sole argument; index workers must use the exact
 * build-bound `cli --index-worker ...` grammar. */
cbm_daemon_process_role_t cbm_daemon_process_role(int argc, char *const argv[]);

/* True only for externally launched long-lived frontends. Internal daemon and
 * worker processes plus one-shot local CLI calls never count as client leases. */
bool cbm_daemon_process_role_requires_client(cbm_daemon_process_role_t role);

/* Construct the one stable per-account endpoint. The endpoint identity is the
 * product rendezvous key: executable path, semantic version, build hash, and
 * ABI values must never create parallel daemon namespaces. */
cbm_daemon_ipc_endpoint_t *cbm_daemon_bootstrap_endpoint_new(const char *runtime_parent);

#ifdef CBM_ENABLE_TEST_SEAMS
/* Test runners only; no product binary arms it. Once armed, an endpoint
 * request that names no runtime parent while CBM_RUNTIME_DIR is unset (one
 * that would resolve to the account-wide default rendezvous, where the
 * developer's live daemon listens) is refused with a diagnostic on stderr. */
void cbm_daemon_bootstrap_forbid_default_runtime_for_test(bool forbid);
/* The same decision cbm_daemon_bootstrap_endpoint_new makes, without
 * resolving anything: true when that call would be refused. */
bool cbm_daemon_bootstrap_default_runtime_refused_for_test(const char *runtime_parent);
#endif

/* Cross-platform launch policy for the daemon child. The child is invoked
 * directly (never through a shell), with exactly argv[0] plus the one hidden
 * internal argument. It is detached from the launching client's lifetime and
 * inherits no standard handles; logical client leases govern its lifetime. */
typedef struct {
    const char *executable_path;
    const char *argv[CBM_DAEMON_BOOTSTRAP_LAUNCH_ARGC + 1U];
    size_t argc;
    bool detached;
    bool inherit_standard_handles;
    bool use_shell;
} cbm_daemon_bootstrap_launch_spec_t;

bool cbm_daemon_bootstrap_launch_spec_init(const char *executable_path,
                                           cbm_daemon_bootstrap_launch_spec_t *spec_out);

/* Same launch policy, but the child is born PERMANENT: it survives its last
 * client disconnect and stops only via `daemon stop`, the install/update
 * drain, or an explicit process kill. Only `daemon start` uses this. */
bool cbm_daemon_bootstrap_launch_spec_init_permanent(const char *executable_path,
                                                     cbm_daemon_bootstrap_launch_spec_t *spec_out);

typedef enum {
    CBM_DAEMON_BOOTSTRAP_FAILED = 0,
    CBM_DAEMON_BOOTSTRAP_BYPASSED,
    CBM_DAEMON_BOOTSTRAP_CONNECTED,
    CBM_DAEMON_BOOTSTRAP_CONFLICT,
} cbm_daemon_bootstrap_status_t;

typedef struct {
    cbm_daemon_process_role_t role;
    const cbm_daemon_ipc_endpoint_t *endpoint;
    const cbm_daemon_build_identity_t *identity;
    const char *executable_path;
    uint32_t connect_timeout_ms;
    uint32_t startup_timeout_ms;
    /* `daemon start` only: an absent endpoint is replaced by a PERMANENT
     * generation instead of an ephemeral one. Client bootstraps leave this
     * false — they must never mint permanence implicitly. */
    bool spawn_permanent;
} cbm_daemon_bootstrap_config_t;

typedef struct {
    cbm_daemon_bootstrap_status_t status;
    cbm_daemon_runtime_client_t *client;
    cbm_daemon_runtime_connect_result_t connect_result;
    bool daemon_spawned;
    char message[CBM_DAEMON_CONFLICT_MESSAGE_SIZE];
    /* #2277: filled by the client on a CONFLICT only — who holds the
     * endpoint and how to clear it (cbm_daemon_conflict_remedy_format). */
    char remedy[CBM_DAEMON_CONFLICT_REMEDY_SIZE];
} cbm_daemon_bootstrap_result_t;

/* A probe distinguishes an absent endpoint from a reserved endpoint whose
 * listener is STARTING, saturated, or otherwise temporarily unable to admit
 * this client. RESERVED and TERMINAL are wait states for the observed
 * generation. If it later becomes truly absent, this same attempt re-enters
 * startup serialization and may launch exactly one replacement. */
typedef enum {
    CBM_DAEMON_BOOTSTRAP_PROBE_ERROR = 0,
    CBM_DAEMON_BOOTSTRAP_PROBE_UNAVAILABLE,
    CBM_DAEMON_BOOTSTRAP_PROBE_RESERVED,
    CBM_DAEMON_BOOTSTRAP_PROBE_CONNECTED,
    CBM_DAEMON_BOOTSTRAP_PROBE_CONFLICT,
    CBM_DAEMON_BOOTSTRAP_PROBE_TERMINAL,
} cbm_daemon_bootstrap_probe_status_t;

/* Deterministic policy seam shared by production probing and unit contracts.
 * lifetime_status follows the IPC reservation tri-state (1 held, 0 free,
 * -1 error). Every protocol-level REJECTED response is RESERVED unless its
 * message explicitly reports terminal shutdown; it is never UNAVAILABLE. */
cbm_daemon_bootstrap_probe_status_t cbm_daemon_bootstrap_classify_failed_connect(
    const cbm_daemon_runtime_connect_result_t *connect_result, int lifetime_status);

typedef void *cbm_daemon_bootstrap_lock_t;
typedef void *cbm_daemon_bootstrap_cohort_t;

/* Durable daemon start-failure record (#1828). A detached daemon has no
 * stderr and no channel back to the client that launched it; when its
 * listener publication fails (a full /tmp, for instance) the client used to
 * respawn it for the whole startup deadline and then report "active or
 * starting". The host now appends one record per failed start to
 * <cache>/logs/cbm-daemon.start-failures.log -- the same owner-only log
 * directory as cbm-daemon.log, deliberately NOT the runtime directory: that
 * one is exactly what a full /tmp cannot write, and a new artifact there
 * would entangle stale-generation cleanup. A waiting client reads the newest
 * record for its endpoint that is not older than its own spawn and fails
 * immediately with the cause. Diagnostic only: policy never reads it. */
enum { CBM_DAEMON_BOOTSTRAP_COMPONENT_CAP = 32 };
typedef struct {
    uint64_t recorded_at_s; /* wall clock, seconds */
    uint64_t pid;
    char component[CBM_DAEMON_BOOTSTRAP_COMPONENT_CAP];  /* host component that refused */
    char stage[CBM_DAEMON_IPC_LISTEN_FAILURE_STAGE_CAP]; /* IPC stage, "" when none */
    int errno_value;                                     /* 0 when unknown */
    char path[CBM_DAEMON_IPC_LISTEN_FAILURE_PATH_CAP];   /* "" when none */
} cbm_daemon_bootstrap_start_failure_t;

/* <cache>/logs, the owner-only directory that holds every daemon log. */
bool cbm_daemon_bootstrap_log_directory(char *out, size_t capacity);
/* Append one record for this process's most recent listener failure detail
 * (cbm_daemon_ipc_listen_failure_detail) under `component`. */
bool cbm_daemon_bootstrap_start_failure_record(const char *log_directory,
                                               const cbm_daemon_ipc_endpoint_t *endpoint,
                                               const char *component);
/* Newest record for `endpoint` recorded at or after not_before_s. Returns 1
 * and fills out_failure, 0 when none matches, -1 when the log directory or
 * file cannot be validated. */
int cbm_daemon_bootstrap_start_failure_read(const char *log_directory,
                                            const cbm_daemon_ipc_endpoint_t *endpoint,
                                            uint64_t not_before_s,
                                            cbm_daemon_bootstrap_start_failure_t *out_failure);
/* The client-facing sentence: "CBM daemon failed to start: <stage> failed
 * with ENOSPC (No space left on device) at <path>; see <log>". */
void cbm_daemon_bootstrap_start_failure_format(const cbm_daemon_bootstrap_start_failure_t *failure,
                                               const char *log_directory, char *out,
                                               size_t capacity);

/* Injectable OS/runtime boundary used by the deterministic unit contract.
 * Production callers use cbm_daemon_bootstrap_execute(), whose built-in
 * operations delegate to daemon IPC/runtime and write visible diagnostics to
 * stderr. Lock acquisition uses the IPC tri-state convention: 1 acquired,
 * 0 held by another starter, -1 error. */
typedef struct {
    void *context;
    cbm_version_cohort_status_t (*cohort_acquire)(void *context,
                                                  const cbm_daemon_ipc_endpoint_t *endpoint,
                                                  const cbm_daemon_build_identity_t *identity,
                                                  uint64_t deadline_ms,
                                                  cbm_daemon_bootstrap_cohort_t *cohort_out,
                                                  cbm_daemon_conflict_t *conflict_out);
    void (*cohort_release)(void *context, cbm_daemon_bootstrap_cohort_t cohort);
    cbm_daemon_bootstrap_probe_status_t (*probe)(void *context,
                                                 const cbm_daemon_ipc_endpoint_t *endpoint,
                                                 const cbm_daemon_build_identity_t *identity,
                                                 uint32_t timeout_ms,
                                                 cbm_daemon_runtime_client_t **client_out,
                                                 cbm_daemon_runtime_connect_result_t *result_out);
    int (*startup_lock_try_acquire)(void *context, const cbm_daemon_ipc_endpoint_t *endpoint,
                                    cbm_daemon_bootstrap_lock_t *lock_out);
    /* Called with startup serialization still held immediately before spawn.
     * It releases only migration-era compatibility ownership that the child
     * must reacquire for its lifetime; the ordinary startup lock stays held. */
    bool (*startup_lock_prepare_handoff)(void *context, cbm_daemon_bootstrap_lock_t lock);
    /* Retry-safe: success consumes and clears *lock_io; false retains it. */
    bool (*startup_lock_release)(void *context, cbm_daemon_bootstrap_lock_t *lock_io);
    bool (*spawn_daemon)(void *context, const cbm_daemon_bootstrap_launch_spec_t *spec);
    void (*visible_diagnostic)(void *context, const char *message);
    /* Optional. After this attempt spawned a daemon, report a start-failure
     * record for the endpoint not older than not_before_s (1 found, 0 none,
     * -1 unreadable). A found record ends the wait immediately (#1828). */
    int (*start_failure_probe)(void *context, const cbm_daemon_ipc_endpoint_t *endpoint,
                               uint64_t not_before_s,
                               cbm_daemon_bootstrap_start_failure_t *out_failure);
} cbm_daemon_bootstrap_ops_t;

cbm_daemon_bootstrap_status_t cbm_daemon_bootstrap_execute(
    const cbm_daemon_bootstrap_config_t *config, cbm_daemon_bootstrap_result_t *result_out);

/* Test seam for the same state machine. All callbacks are synchronous and
 * borrowed for the duration of the call. */
#ifdef CBM_ENABLE_TEST_SEAMS
/* Replace ONLY the production spawn while every other production operation
 * (cohort, probe, startup lock, handoff) stays real. A test forks a real
 * daemon host in place of exec'ing the product binary, so the complete
 * client/daemon rendezvous runs in one deterministic process tree (#1828). */
typedef bool (*cbm_daemon_bootstrap_spawn_fn)(void *context,
                                              const cbm_daemon_bootstrap_launch_spec_t *spec);
void cbm_daemon_bootstrap_spawn_override_set_for_test(cbm_daemon_bootstrap_spawn_fn spawn,
                                                      void *context);
#endif

cbm_daemon_bootstrap_status_t cbm_daemon_bootstrap_execute_with_ops(
    const cbm_daemon_bootstrap_config_t *config, const cbm_daemon_bootstrap_ops_t *ops,
    cbm_daemon_bootstrap_result_t *result_out);

#endif /* CBM_DAEMON_BOOTSTRAP_H */