Documentation
¶
Overview ¶
Package hooks runs external hook executables at box lifecycle events. A hook is any program llmbox runs as a subprocess, exchanging JSON over stdin/stdout per the hookproto contract. This keeps llmbox free of any knowledge of what a hook does — for example, a granular hook (in its own repo) mints a subject token and installs the granular CLIs into each box, while llmbox only injects the files the hook returns and replays the hook's opaque state on destroy.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type BoxInfo ¶
BoxInfo describes a box to a hook. It aliases the wire type so callers need not import hookproto just to build one.
type File ¶
File is a resolved file a hook asked to inject into a box: its content already decoded and its mode already parsed, ready to hand to the Docker layer.
type Runner ¶
type Runner struct {
// contains filtered or unexported fields
}
Runner runs a fixed list of hook executables for every event. A nil *Runner is a no-op (no hooks configured), so callers can hold one without nil-checking every call site.
func New ¶
New builds a Runner over the given hook executable paths, or returns nil when the list is empty so the integration stays opt-in (a nil *Runner is a no-op).
@arg execs The hook executable paths to run for every lifecycle event. @return *Runner A Runner over the executables, or nil when execs is empty.
@testcase TestNewEmptyIsNil returns nil for an empty executable list. @testcase TestOnCreateInjectsFilesAndState runs a configured hook executable.
func (*Runner) OnCreate ¶
func (r *Runner) OnCreate(ctx context.Context, box BoxInfo) (files []File, state map[string]string, err error)
OnCreate runs every hook's box.create event, returning the files to inject into the box and a map from hook executable to the opaque state it returned (to be persisted and replayed on destroy). A nil Runner returns nothing. The first hook that fails aborts and returns its error along with the state gathered so far, so the caller can run OnDestroy to undo partial work.
@arg ctx Context for the hook subprocess calls. @arg box The box the create event concerns. @return files The files every hook asked to inject into the box. @return state A map from hook executable to the opaque state it returned. @error error if a hook fails to run or returns an unusable response.
@testcase TestOnCreateNilIsNoop returns nothing for a nil Runner. @testcase TestOnCreateInjectsFilesAndState aggregates files and keys state by hook. @testcase TestOnCreateFailingHookErrors surfaces a failing hook's error and partial state.
func (*Runner) OnDestroy ¶
OnDestroy runs every hook's box.destroy event, replaying the opaque state each hook returned at create time (from the map keyed by hook executable). It is best-effort: it runs all hooks and returns the first error, so a caller can log it while still tearing the box down. A nil Runner or empty state is a no-op.
@arg ctx Context for the hook subprocess calls. @arg box The box the destroy event concerns. @arg state The per-hook state captured by OnCreate. @error error if any hook fails to run; the remaining hooks still run.
@testcase TestOnDestroyNilIsNoop does nothing for a nil Runner or empty state. @testcase TestOnDestroyReplaysState passes each hook back its own create-time state.
Source Files