Documentation
¶
Overview ¶
Package hooks implements the storage substrate hook subscribers (P1-04 and P1-05). They run external shell commands in response to bus events.
Configuration is loaded from openlore.yml. Defaults: non-fatal hook errors. Set fail_on_error: true on a hook to flip to fatal.
Index ¶
Constants ¶
const DefaultDebounce = 2 * time.Second
DefaultDebounce is the pre_read debounce window if Debounce is unset.
const DefaultHookTimeout = 30 * time.Second
DefaultHookTimeout is the per-hook wall-clock cap if Timeout is unset.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Config ¶
type Config struct {
// DataDir is the disk root passed to hooks via OPENLORE_DATA_DIR.
DataDir string `yaml:"data_dir"`
// Hooks is the per-event command list.
Hooks HookSet `yaml:"hooks"`
}
Config is the openlore.yml hooks block.
Example:
data_dir: /var/lib/openlore
hooks:
on_startup:
- cmd: "/usr/local/bin/openlore-restore"
timeout: 30s
pre_read:
- cmd: "/usr/local/bin/openlore-pull"
debounce: 2s
post_write:
- cmd: "/usr/local/bin/openlore-version"
fail_on_error: true
type HookCmd ¶
type HookCmd struct {
// Cmd is the shell command line to execute. Run via `sh -c`.
Cmd string `yaml:"cmd"`
// Timeout caps the command's wall-clock runtime. Zero means
// DefaultHookTimeout.
Timeout time.Duration `yaml:"timeout"`
// FailOnError makes a non-zero exit fatal to the publisher. Defaults to
// false (errors logged, never propagated).
FailOnError bool `yaml:"fail_on_error"`
// Debounce coalesces repeated pre_read hits on the same path. Zero means
// DefaultDebounce. Only applies to pre_read hooks; ignored elsewhere.
Debounce time.Duration `yaml:"debounce"`
}
HookCmd is a single shell command to run on an event.
type HookSet ¶
type HookSet struct {
OnStartup []HookCmd `yaml:"on_startup"`
PreRead []HookCmd `yaml:"pre_read"`
PostWrite []HookCmd `yaml:"post_write"`
}
HookSet groups commands by event kind.
type Runner ¶
type Runner interface {
// Run executes cmd with the given env. Returns the command's combined
// output (stdout+stderr) and any execution error. Honour ctx for
// cancellation/timeout.
Run(ctx context.Context, cmd string, env []string) ([]byte, error)
}
Runner executes a shell command line. Production uses ShellRunner; tests substitute a fake.
type Subscriber ¶
type Subscriber struct {
// contains filtered or unexported fields
}
Subscriber wraps a single HookCmd as an eventbus.Subscriber.
Env-var protocol passed to the child process:
- OPENLORE_DATA_DIR — server data root
- OPENLORE_PATH — virtual path the event refers to
- OPENLORE_AGENT — publishing agent ID (or empty)
- OPENLORE_BYTES — byte count (post_write only)
- OPENLORE_EVENT — event kind (on_startup / pre_read / post_write)
- OPENLORE_PARTITION — partition slug (or empty)
func NewSubscriber ¶
func NewSubscriber(name string, kind eventbus.EventKind, cmd HookCmd, dataDir string, runner Runner, logger *slog.Logger) *Subscriber
NewSubscriber wraps a HookCmd for a specific event kind.
func Subscribe ¶
Subscribe wires every HookCmd in cfg as an eventbus.Subscriber on bus. It returns the list of registered Subscribers (mostly for tests).
func (*Subscriber) Handle ¶
Handle runs the configured shell command for the event, if the event kind matches. Pre-read events are debounced per-path. Honours the per-hook timeout. Errors are returned for the bus to decide fatality.
func (*Subscriber) Name ¶
func (s *Subscriber) Name() string
func (*Subscriber) Required ¶
func (s *Subscriber) Required() bool
Source Files