Documentation
¶
Overview ¶
Package queueactions hosts the shared business logic behind the queue resolution verbs: clarify, unclarify, retry, clear, stop.
These functions are the single source of truth for the state mutations and audit-trail entries that back the CLI verbs (forge queue clarify, etc.) and the IPC handlers (queue_clarify, queue_unclarify, queue_retry, queue_clear, queue_stop). Daemon-specific orchestration that surrounds each action — shelling out to `bd`, refreshing in-memory caches, kicking the poller — is not part of this package; callers compose those on top of the action.
Multi-forge safety is enforced inside each function: if the caller supplies a forge_id that does not match the QueueHandle's local forge_id, the action is refused with ErrForgeMismatch. A caller that omits forge_id retains the historical single-forge behaviour.
Index ¶
- Variables
- func Clarify(ctx context.Context, q QueueHandle, p Params) error
- func Clear(ctx context.Context, q QueueHandle, p Params) error
- func Retry(ctx context.Context, q QueueHandle, p Params) (bool, error)
- func SanitizeControl(s string) string
- func Stop(ctx context.Context, q QueueHandle, p Params) (string, error)
- func Unclarify(ctx context.Context, q QueueHandle, p Params) error
- type Params
- type QueueHandle
Constants ¶
This section is empty.
Variables ¶
var ErrForgeMismatch = errors.New("forge_id does not match owning forge")
ErrForgeMismatch is returned when the caller's forge_id does not match the forge that owns the worker/bead being acted on. This is the multi-forge safety check that prevents one Forge instance from clobbering another's state when they share a database or are addressed by a shared client (e.g. the web UI).
var ErrMissingAnvil = errors.New("anvil is required")
ErrMissingAnvil indicates the caller did not supply an anvil name.
var ErrMissingBeadID = errors.New("bead_id is required")
ErrMissingBeadID indicates the caller did not supply a bead identifier.
var ErrMissingReason = errors.New("reason is required")
ErrMissingReason indicates the caller did not supply a reason/note where the action requires one (currently: clarify).
Functions ¶
func Clarify ¶
func Clarify(ctx context.Context, q QueueHandle, p Params) error
Clarify marks a bead as needing human clarification before further dispatch. Mirrors the legacy set_clarification IPC handler. The note is required and captured both as the bead's clarification reason and in the audit event.
func Clear ¶
func Clear(ctx context.Context, q QueueHandle, p Params) error
Clear drops the needs-attention flags from a bead's retry row without re-dispatching it. Idempotent — safe on an already-clean bead.
func Retry ¶
Retry resets the dispatch circuit breaker for a bead so the next poll cycle re-dispatches it. Only the bead-level reset lives here; PR-level retry (resetting bellows fix counts) remains in the daemon because it requires lifecycle and bellows references that have no place behind the shared interface.
The returned bool is true when a circuit-breaker row with DispatchFailures>0 was found and cleared; callers can use this to preserve the prior IPC response wording ("retry state reset" vs "retry reset").
func SanitizeControl ¶
SanitizeControl strips control characters (except newline) from operator input that ends up in the bead's clarification_reason and event message. Exported so daemon log sites can apply the same transform and remain consistent with what the audit event records.
func Stop ¶
Stop terminates any running worker for the bead, marks the bead as needing clarification (preventing both auto and manual re-dispatch), and writes an audit event. The caller is responsible for any follow-up shell work — most notably `bd update --status=open --assignee=` to release the claim.
The returned string is the worker ID that was signalled and marked failed, or empty if no active worker was found. Callers can log this to preserve operator visibility into which process was terminated.
Types ¶
type Params ¶
Params bundles the inputs common to all queue resolution actions. AnvilName is canonicalised by the caller before invocation. Note is the operator's free-form explanation, captured in the audit event.
type QueueHandle ¶
type QueueHandle interface {
// LocalForgeID returns the forge_id of the Forge instance handling the
// request. Compared against Params.ForgeID for the multi-forge safety
// check.
LocalForgeID() string
SetClarificationNeeded(beadID, anvil string, needed bool, reason string) error
ClearNeedsAttention(beadID, anvil string) error
GetRetry(beadID, anvil string) (*state.RetryRecord, error)
ResetRetry(beadID, anvil string) error
ActiveWorkerByBeadAndAnvil(beadID, anvil string) (*state.Worker, error)
UpdateWorkerStatus(workerID string, status state.WorkerStatus) error
LogEvent(typ state.EventType, message, beadID, anvil string) error
}
QueueHandle abstracts the daemon state operations that the shared actions rely on. The daemon implements this directly against state.DB; tests pass in a fake to verify behaviour without a real database.
Source Files