fsq

package
v0.49.2 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jul 27, 2026 License: MIT Imports: 16 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	DLQSchemaVersion = "amq/dlq/v1"
	MaxRetries       = 3
)
View Source 
const (
	BoxNew = "new"
	BoxCur = "cur"
)

Variables

This section is empty.

Functions

func AgentBase 

func AgentBase(root, agent string) string

func AgentDLQCur added in v0.9.0 

func AgentDLQCur(root, agent string) string

func AgentDLQNew added in v0.9.0 

func AgentDLQNew(root, agent string) string

func AgentDLQTmp added in v0.9.0 

func AgentDLQTmp(root, agent string) string

func AgentInboxCur 

func AgentInboxCur(root, agent string) string

func AgentInboxNew 

func AgentInboxNew(root, agent string) string

func AgentInboxTmp 

func AgentInboxTmp(root, agent string) string

func AgentMailboxPath added in v0.48.0 

func AgentMailboxPath(root, agent string, leaf MailboxLeaf) string

AgentMailboxPath returns one required leaf below an agent mailbox.

func AgentOutboxSent 

func AgentOutboxSent(root, agent string) string

func AgentReceipts added in v0.31.0 

func AgentReceipts(root, agent string) string

func DeliverToExistingInbox added in v0.24.0 

func DeliverToExistingInbox(root *DeliveryRoot, agent, filename string, data []byte) (string, error)

DeliverToExistingInbox delivers a message to a foreign root's inbox using Maildir semantics (tmp -> new). Unlike DeliverToInboxes, it never creates directories — the target inbox must already exist. This prevents a sender from accidentally scaffolding structure in a peer project.

func DeliverToInbox 

func DeliverToInbox(root *DeliveryRoot, agent, filename string, data []byte) (string, error)

DeliverToInbox writes a message using Maildir semantics (tmp -> new). It returns the final path in inbox/new.

func DeliverToInboxes added in v0.2.0 

func DeliverToInboxes(root *DeliveryRoot, recipients []string, filename string, data []byte) (map[string]string, error)

DeliverToInboxes writes a message to multiple inboxes. On partial failure, committed deliveries remain in new/ and undelivered tmp files are removed.

func EnsureAgentDirs 

func EnsureAgentDirs(root, agent string) error

func EnsureRootDirs 

func EnsureRootDirs(root string) error

func FindDLQMessage added in v0.9.0 

func FindDLQMessage(root *DeliveryRoot, agent, filename string) (string, string, error)

FindDLQMessage locates a DLQ message in dlq/new or dlq/cur.

func FindMessage 

func FindMessage(root, agent, filename string) (string, string, error)

func FindTmpFilesOlderThan 

func FindTmpFilesOlderThan(root string, cutoff time.Time) ([]string, error)

func GenerateDLQID added in v0.9.0 

func GenerateDLQID() string

GenerateDLQID creates a unique ID for a DLQ envelope.

func ListAgents 

func ListAgents(root string) ([]string, error)

func MailboxRootRelativePath added in v0.48.0 

func MailboxRootRelativePath(agent string, leaf MailboxLeaf) string

MailboxRootRelativePath returns one required leaf relative to a queue root.

func MoveCurToDLQ added in v0.39.0 

func MoveCurToDLQ(root *DeliveryRoot, agent, filename, originalID, failureReason, failureDetail string) (string, error)

MoveCurToDLQ moves an already-claimed inbox/cur message to dlq/new.

func MoveDLQNewToCur added in v0.9.0 

func MoveDLQNewToCur(root *DeliveryRoot, agent, filename string) error

MoveDLQNewToCur moves a DLQ message from new to cur (marks as inspected).

func MoveNewToCur 

func MoveNewToCur(root *DeliveryRoot, agent, filename string) error

func MoveToDLQ added in v0.9.0 

func MoveToDLQ(root *DeliveryRoot, agent, filename, originalID, failureReason, failureDetail string) (string, error)

MoveToDLQ moves a failed message from inbox/new to dlq/new with envelope.

func OpenRegularNoFollow added in v0.40.0 

func OpenRegularNoFollow(path string) (*os.File, os.FileInfo, error)

OpenRegularNoFollow opens path only if it is a regular file and not a symlink.

func ReadRegularNoFollow added in v0.40.0 

func ReadRegularNoFollow(path string) ([]byte, error)

func RetryFromDLQ added in v0.9.0 

func RetryFromDLQ(root *DeliveryRoot, agent, dlqFilename string, force bool) error

RetryFromDLQ moves a message from DLQ back to inbox/new for reprocessing. Returns error if retry_count >= MaxRetries and force is false.

func SyncDir 

func SyncDir(dir string) error

SyncDir fsyncs a directory to ensure directory entries are durable.

func ValidateHandle added in v0.16.0 

func ValidateHandle(agent string) error

ValidateHandle returns an error if the agent handle contains path traversal characters or does not match the allowed pattern.

func ValidateMessageFilename added in v0.40.0 

func ValidateMessageFilename(filename string) error

ValidateMessageFilename validates an inbox or DLQ message filename.

func WriteFileAtomic 

func WriteFileAtomic(dir, filename string, data []byte, perm os.FileMode) (string, error)

WriteFileAtomic writes data to a temporary file in dir and renames it into place.

Types

type CommittedDurabilityError added in v0.45.0 

type CommittedDurabilityError struct {
	FinalPath string
	Recipient string
	Err       error
}

CommittedDurabilityError means the visible rename succeeded, but the destination directory could not be synced. Retrying with a new identifier may duplicate an artifact that is already present at FinalPath.

func (*CommittedDurabilityError) Error added in v0.45.0 

func (e *CommittedDurabilityError) Error() string

func (*CommittedDurabilityError) Unwrap added in v0.45.0 

func (e *CommittedDurabilityError) Unwrap() error

type DLQEnvelope added in v0.9.0 

type DLQEnvelope struct {
	Schema        string `json:"schema"`
	ID            string `json:"id"`
	OriginalID    string `json:"original_id"`
	OriginalFile  string `json:"original_file"`
	FailureReason string `json:"failure_reason"`
	FailureDetail string `json:"failure_detail"`
	FailureTime   string `json:"failure_time"`
	RetryCount    int    `json:"retry_count"`
	SourceDir     string `json:"source_dir"`
}

DLQEnvelope wraps a failed message with failure metadata.

func ReadDLQEnvelope added in v0.9.0 

func ReadDLQEnvelope(root *DeliveryRoot, path string) (*DLQEnvelope, []byte, error)

ReadDLQEnvelope reads and parses a DLQ message.

func ReadDLQEnvelopePath added in v0.45.0 

func ReadDLQEnvelopePath(path string) (*DLQEnvelope, []byte, error)

ReadDLQEnvelopePath is the legacy pathname reader used only by non-mutating listing code. Mutating DLQ flows must use ReadDLQEnvelope with a capability.

type DLQTransitionError added in v0.45.0 

type DLQTransitionError struct {
	EnvelopePath   string
	SourcePath     string
	SourceRetained bool
	Err            error
}

DLQTransitionError reports that a DLQ envelope is visible but its directory sync failed, so the claimed source was deliberately retained for recovery.

func (*DLQTransitionError) Error added in v0.45.0 

func (e *DLQTransitionError) Error() string

func (*DLQTransitionError) Unwrap added in v0.45.0 

func (e *DLQTransitionError) Unwrap() error

type DeliveryRoot added in v0.45.0 

type DeliveryRoot struct {
	// contains filtered or unexported fields
}

DeliveryRoot is an authorized, pinned filesystem capability for one AMQ tree. All delivery paths are resolved relative to the open directory rather than by reopening Base through the ambient filesystem namespace.

func OpenDeliveryRoot added in v0.45.0 

func OpenDeliveryRoot(base string, expected DeliveryRootIdentity) (*DeliveryRoot, error)

OpenDeliveryRoot opens base once and proves the opened directory is the same physical object authorized by expected. Subsequent operations are pinned to that handle and never reopen base through the ambient namespace.

func (*DeliveryRoot) Base added in v0.45.0 

func (r *DeliveryRoot) Base() string

Base returns the authorized path for diagnostics only. Filesystem operations must stay relative to the pinned root.

func (*DeliveryRoot) Close added in v0.45.0 

func (r *DeliveryRoot) Close() error

func (*DeliveryRoot) DisplayPath added in v0.45.0 

func (r *DeliveryRoot) DisplayPath(name string) string

DisplayPath returns the diagnostic path for a root-relative name. The result must not be used for filesystem I/O.

func (*DeliveryRoot) OpenRegularNoFollow added in v0.49.0 

func (r *DeliveryRoot) OpenRegularNoFollow(name string) (*os.File, os.FileInfo, error)

OpenRegularNoFollow opens a root-relative regular file through the pinned capability while refusing symlinks and detecting replacement during open. The caller must close the returned file.

func (*DeliveryRoot) ReadDir added in v0.45.0 

func (r *DeliveryRoot) ReadDir(name string) ([]os.DirEntry, error)

ReadDir reads a root-relative directory through the pinned capability.

func (*DeliveryRoot) ReadFile added in v0.45.0 

func (r *DeliveryRoot) ReadFile(name string) ([]byte, error)

ReadFile reads a root-relative file through the pinned capability.

func (*DeliveryRoot) ReadRegularNoFollow added in v0.45.0 

func (r *DeliveryRoot) ReadRegularNoFollow(name string) ([]byte, error)

ReadRegularNoFollow reads a root-relative regular file while refusing an initially symlinked artifact and detecting replacement between lstat/open.

func (*DeliveryRoot) Remove added in v0.45.0 

func (r *DeliveryRoot) Remove(name string) error

Remove removes a root-relative path through the pinned capability.

func (*DeliveryRoot) Stat added in v0.45.0 

func (r *DeliveryRoot) Stat(name string) (os.FileInfo, error)

Stat stats a root-relative path through the pinned capability.

func (*DeliveryRoot) SyncDir added in v0.45.0 

func (r *DeliveryRoot) SyncDir(name string) error

SyncDir syncs a root-relative directory through the pinned capability.

func (*DeliveryRoot) VerifyBase added in v0.45.0 

func (r *DeliveryRoot) VerifyBase() error

VerifyBase reports a lexical alias change after authorization. The open root remains the security boundary even if an alias changes immediately after this check; this verification makes a detected swap fail closed instead of silently delivering into the formerly named tree.

func (*DeliveryRoot) WriteFileAtomic added in v0.45.0 

func (r *DeliveryRoot) WriteFileAtomic(dir, filename string, data []byte, perm os.FileMode) (string, error)

WriteFileAtomic writes a root-relative file through the pinned capability.

type DeliveryRootIdentity added in v0.45.0 

type DeliveryRootIdentity struct {
	// contains filtered or unexported fields
}

DeliveryRootIdentity is an opaque physical-identity snapshot taken at the authorization boundary and consumed when the directory capability is opened.

func SnapshotDeliveryRoot added in v0.45.0 

func SnapshotDeliveryRoot(base string) (DeliveryRootIdentity, error)

SnapshotDeliveryRoot captures the physical directory identity at the authorization boundary. The snapshot is intentionally opaque so callers cannot forge or reinterpret it.

func (DeliveryRootIdentity) FileInfo added in v0.45.0 

func (i DeliveryRootIdentity) FileInfo() os.FileInfo

FileInfo returns the captured identity for comparison with an existing platform identity token. Filesystem operations cannot be performed through this value.

type MailboxInspection added in v0.48.0 

type MailboxInspection struct {
	Handle         string                  `json:"handle"`
	Provenance     MailboxProvenance       `json:"provenance"`
	Status         string                  `json:"status"`
	Issues         []string                `json:"issues"`
	Paths          []MailboxPathInspection `json:"paths,omitempty"`
	RepairEligible bool                    `json:"repair_eligible"`
	Remedy         string                  `json:"remedy,omitempty"`
	CreatedPaths   []string                `json:"created_paths,omitempty"`
}

type MailboxInventory added in v0.48.0 

type MailboxInventory struct {
	Mailboxes          []MailboxInspection
	ActiveConfigStatus string
	ActiveConfigIssue  string
	ConfiguredAgents   []string
	AgentsState        MailboxPathState
	AgentsIssue        string
	RepairAuthorized   bool
}

func InspectMailboxLayout added in v0.48.0 

func InspectMailboxLayout(root *DeliveryRoot) (MailboxInventory, error)

InspectMailboxLayout builds the configured+discovered mailbox inventory through the pinned root capability without changing the filesystem.

type MailboxLeaf added in v0.48.0 

type MailboxLeaf string

MailboxLeaf identifies one required per-agent mailbox leaf. 

const (
	MailboxInboxTmp   MailboxLeaf = "inbox/tmp"
	MailboxInboxNew   MailboxLeaf = "inbox/new"
	MailboxInboxCur   MailboxLeaf = "inbox/cur"
	MailboxOutboxSent MailboxLeaf = "outbox/sent"
	MailboxDLQTmp     MailboxLeaf = "dlq/tmp"
	MailboxDLQNew     MailboxLeaf = "dlq/new"
	MailboxDLQCur     MailboxLeaf = "dlq/cur"
	MailboxReceipts   MailboxLeaf = "receipts"
)

func RequiredMailboxLeaves added in v0.48.0 

func RequiredMailboxLeaves() []MailboxLeaf

RequiredMailboxLeaves returns the one ordered mailbox-layout contract.

type MailboxPathInspection added in v0.48.0 

type MailboxPathInspection struct {
	Path  string           `json:"path"`
	State MailboxPathState `json:"state"`
	Mode  string           `json:"mode,omitempty"`
}

type MailboxPathState added in v0.48.0 

type MailboxPathState string
const (
	MailboxPathDirectory               MailboxPathState = "directory"
	MailboxPathMissing                 MailboxPathState = "missing"
	MailboxPathSymlink                 MailboxPathState = "symlink"
	MailboxPathNonDirectory            MailboxPathState = "non_directory"
	MailboxPathUnreadable              MailboxPathState = "unreadable"
	MailboxPathChangedDuringInspection MailboxPathState = "changed_during_inspection"
)

type MailboxProvenance added in v0.48.0 

type MailboxProvenance string
const (
	MailboxConfigured              MailboxProvenance = "configured"
	MailboxDiscovered              MailboxProvenance = "discovered"
	MailboxConfiguredAndDiscovered MailboxProvenance = "configured_and_discovered"
)

type MailboxRepairFailure added in v0.48.0 

type MailboxRepairFailure struct {
	Code                    string `json:"code"`
	Stage                   string `json:"stage"`
	Path                    string `json:"path,omitempty"`
	Message                 string `json:"message"`
	DurabilityIndeterminate bool   `json:"durability_indeterminate,omitempty"`
}

type MailboxRepairResult added in v0.48.0 

type MailboxRepairResult struct {
	Status       string                `json:"status"`
	CreatedPaths []string              `json:"created_paths,omitempty"`
	Failure      *MailboxRepairFailure `json:"failure,omitempty"`
	Inventory    MailboxInventory      `json:"-"`
}

func RepairMailboxLayout added in v0.48.0 

func RepairMailboxLayout(root *DeliveryRoot) MailboxRepairResult

RepairMailboxLayout validates the complete configured set before creating any directory and returns exact partial results if creation later fails.

type PartialDeliveryError added in v0.39.0 

type PartialDeliveryError struct {
	Delivered map[string]string
	Failed    string
	Pending   []string
	Err       error
}

PartialDeliveryError reports the delivery state after a multi-recipient delivery fails during the tmp -> new commit phase.

func (*PartialDeliveryError) Error added in v0.39.0 

func (e *PartialDeliveryError) Error() string

func (*PartialDeliveryError) Unwrap added in v0.39.0 

func (e *PartialDeliveryError) Unwrap() error

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.