fsq

package
v0.77.0 Latest Latest
Warning

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

 Go to latest Published: Sep 2, 2026 License: MIT Imports: 19 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	DLQSchemaVersion = "amq/dlq/v1"
	MaxRetries       = 3

	RetryStateReady         = "ready"
	RetryStatePending       = "pending"
	RetryStateDelivered     = "delivered"
	RetryStateIndeterminate = "indeterminate"
)
View Source 
const (
	BoxNew = "new"
	BoxCur = "cur"
)

Variables

View Source 
var (
	// ErrDLQRetryDelivered marks a terminal retry audit. The original delivery
	// may since have been consumed, so filesystem absence does not make this
	// envelope retryable again.
	ErrDLQRetryDelivered = errors.New("DLQ envelope retry already delivered")

	// ErrDLQRetryIndeterminate marks a crash-recovery state where the retry was
	// recorded as pending but its destination is no longer visible. AMQ cannot
	// safely distinguish a never-committed delivery from one already consumed.
	ErrDLQRetryIndeterminate = errors.New("DLQ envelope retry outcome is indeterminate")
)
View Source 
var AfterCreateDirectoryPathExclusiveLstatNotExistForTest func(path string)

AfterCreateDirectoryPathExclusiveLstatNotExistForTest runs after a missing path component is observed with fstatat(AT_SYMLINK_NOFOLLOW) and before exclusive mkdirat. Tests use it to plant a racing symlink at that path.

View Source 
var ErrDeliveryRootChanged = errors.New("delivery root changed after authorization")

ErrDeliveryRootChanged reports that an authorized directory was replaced through its ambient path after the capability was opened.

View Source 
var ErrPathIsSymlink = errors.New("path is a symlink")

ErrPathIsSymlink is returned when exclusive directory creation observes a symlink at a path component that must be a real directory.

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.

A same-name file in both boxes is the recoverable residue of an envelope update: the new state is written to cur before the old new copy is removed. cur is therefore authoritative whenever both exist. Prefer it so a stale pre-update envelope cannot hide a completed retry audit or a newer retry count.

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, error)

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 MoveClaimedCurToDLQ added in v0.49.8 

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

MoveClaimedCurToDLQ moves an inbox/cur message to dlq/new while reconciling a durability-indeterminate claim that already made the message visible in cur. Once the source is removed, any committed error names the visible DLQ envelope rather than the no-longer-present cur artifact.

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

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 OpenMailboxConfigAuthorization added in v0.49.7 

func OpenMailboxConfigAuthorization(configRoot *DeliveryRoot) (*MailboxConfigAuthorization, MailboxInventory, error)

OpenMailboxConfigAuthorization pins the active config through configRoot.

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 StableFileIdentity added in v0.61.0 

func StableFileIdentity(path string) (string, error)

StableFileIdentity returns an opaque physical identity for one regular file. It is used to pin executable targets across a delayed launch boundary.

func StableFileIdentityInfo added in v0.64.0 

func StableFileIdentityInfo(info os.FileInfo) (string, error)

StableFileIdentityInfo returns the opaque identity for an already opened regular-file snapshot.

func StableTreeIdentity added in v0.61.0 

func StableTreeIdentity(path string) (string, error)

StableTreeIdentity returns the opaque physical identity used to bind authority to one project directory. Callers must not parse the token.

func StableTreeIdentityInfo added in v0.61.0 

func StableTreeIdentityInfo(info os.FileInfo) (string, error)

StableTreeIdentityInfo returns the same token from an already authorized filesystem snapshot.

func SyncDir 

func SyncDir(dir string) error

SyncDir fsyncs a directory to ensure directory entries are durable.

func ValidateExistingMailboxLayout added in v0.49.7 

func ValidateExistingMailboxLayout(root *DeliveryRoot, handles ...string) error

ValidateExistingMailboxLayout requires the complete mailbox contract for each requested handle without creating or changing any path.

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 ValidateLegacyHandleForInspection added in v0.49.10 

func ValidateLegacyHandleForInspection(agent string) error

ValidateLegacyHandleForInspection accepts the historical safe single-path component grammar. It exists only so read-only inventory/list operations can surface mailboxes created before leading '-' was rejected. It must not authorize creation, delivery, consumption, repair, wake, or presence writes.

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 ClaimCollisionError added in v0.60.3 

type ClaimCollisionError struct {
	NewPath string
	CurPath string
}

ClaimCollisionError reports a claim rename that found the destination name already present. Normal AMQ flows never hold the same filename in both inbox/new and inbox/cur — a committed claim removes new, and DLQ retry refuses redelivery while a retained cur exists — so a collision means external reintroduction or an invariant violation. It is a loud, terminal condition: the claim is neither won nor lost, and callers must not treat it as either.

func (*ClaimCollisionError) Error added in v0.60.3 

func (e *ClaimCollisionError) Error() string

type CommittedDurabilityError added in v0.45.0 

type CommittedDurabilityError struct {
	FinalPath string
	Recipient string
	Err       error
}

CommittedDurabilityError means the visible rename succeeded, but the affected directory metadata could not be fully 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"`
	RetryState     string `json:"retry_state,omitempty"`
	RetryPending   bool   `json:"retry_pending,omitempty"`
	RetryDelivered bool   `json:"retry_delivered,omitempty"`
	SourceDir      string `json:"source_dir"`
}

DLQEnvelope wraps a failed message with failure metadata.

func InspectDLQEnvelope added in v0.49.8 

func InspectDLQEnvelope(root *DeliveryRoot, agent, filename string) (
	envelope *DLQEnvelope,
	originalContent []byte,
	box string,
	err error,
)

InspectDLQEnvelope reads one DLQ envelope and marks a new envelope inspected while holding the same per-envelope lock used by retry and purge. The returned envelope, body, and box therefore describe one serialized state. When the new-to-cur rename committed but directory durability is indeterminate, box is cur and err is a CommittedDurabilityError.

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 an incomplete DLQ transition where the envelope is visible but the recoverable source is still present. Completed logical transitions with indeterminate durability use CommittedDurabilityError.

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 CreateDirectoryPathExclusive added in v0.65.3 

func CreateDirectoryPathExclusive(path string) (*DeliveryRoot, error)

CreateDirectoryPathExclusive pins the nearest existing parent with nofollow dirfds and exclusive-creates each missing component at 0700. A symlink at a created component is refused; the returned DeliveryRoot is pinned to the created directory capability rather than the ambient lexical path.

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) ClassifyLayout added in v0.60.5 

func (r *DeliveryRoot) ClassifyLayout() (LayoutState, error)

ClassifyLayout inspects the pinned root without writes and reports whether it is an initialized queue, an empty directory, or a foreign tree. An agents/ entry that is not a real directory (symlink, file) is a hostile shape and fails closed with an error.

func (*DeliveryRoot) Close added in v0.45.0 

func (r *DeliveryRoot) Close() error

func (*DeliveryRoot) CreateDirectChildExclusive added in v0.61.0 

func (r *DeliveryRoot) CreateDirectChildExclusive(name string, perm os.FileMode) (*DeliveryRoot, error)

CreateDirectChildExclusive creates one direct, non-symlink child directory and fails if the name already exists. Session create uses this so a racing creator cannot silently open an existing session.

func (*DeliveryRoot) CreateExclusiveFile added in v0.68.0 

func (r *DeliveryRoot) CreateExclusiveFile(relPath string, data []byte, perm os.FileMode) error

CreateExclusiveFile writes a root-relative regular file and refuses if the path already exists. Callers that treat existence as idempotence must check os.ErrExist rather than replacing the file.

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) EnsureAgentDirs added in v0.49.6 

func (r *DeliveryRoot) EnsureAgentDirs(agent string) error

EnsureAgentDirs creates one agent's mailbox layout through the pinned root capability.

func (*DeliveryRoot) EnsureRootDirs added in v0.49.6 

func (r *DeliveryRoot) EnsureRootDirs() error

EnsureRootDirs creates the queue-level layout through the pinned root capability.

func (*DeliveryRoot) FileInfo added in v0.61.0 

func (r *DeliveryRoot) FileInfo() os.FileInfo

FileInfo returns the physical directory snapshot captured when this root capability was opened. Callers may derive an opaque identity token from it; filesystem operations must still use the pinned capability.

func (*DeliveryRoot) OpenDirectChild added in v0.49.7 

func (r *DeliveryRoot) OpenDirectChild(name string) (*DeliveryRoot, error)

OpenDirectChild pins one existing direct, non-symlink child directory beneath the authorized root without creating it.

func (*DeliveryRoot) OpenLockFile added in v0.61.0 

func (r *DeliveryRoot) OpenLockFile(dir, filename string, perm os.FileMode) (*os.File, error)

OpenLockFile opens or creates a root-relative file for advisory locking. The file is opened O_CREATE on its stable name and is never replaced, so flock serializes on one inode. Callers must close the returned file.

func (*DeliveryRoot) OpenOrCreateDirectChild added in v0.49.6 

func (r *DeliveryRoot) OpenOrCreateDirectChild(name string, perm os.FileMode) (*DeliveryRoot, error)

OpenOrCreateDirectChild pins one direct, non-symlink child directory beneath the authorized root. The before/open/after identity checks prevent a child swapped during validation from redirecting later writes through a symlink.

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) PublishInitializedDirectChildExclusive added in v0.62.0 

func (r *DeliveryRoot) PublishInitializedDirectChildExclusive(name string, perm os.FileMode, initialize func(*DeliveryRoot) error) (*DeliveryRoot, error)

PublishInitializedDirectChildExclusive builds a direct child under a hidden sibling name and publishes it only after initialize succeeds. Publication uses the platform's no-replace primitive, so even an uncooperative racing creator can never be overwritten.

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) WithDLQEnvelopeLock added in v0.49.8 

func (r *DeliveryRoot) WithDLQEnvelopeLock(agent, filename string, fn func(*DeliveryRoot) error) error

WithDLQEnvelopeLock runs fn while holding the durable, process-scoped lock for one DLQ envelope. The lock file is retained deliberately: its advisory handle lock is released by the kernel on close or process crash, so no stale O_EXCL sentinel can block a later recovery.

func (*DeliveryRoot) WithPinnedBatch added in v0.49.8 

func (r *DeliveryRoot) WithPinnedBatch(fn func(*DeliveryRoot) error) error

WithPinnedBatch verifies the ambient root identity once, then runs one finite operation entirely through the already-open directory capability. Renaming or replacing the lexical base after the callback starts cannot redirect any batch filesystem operation to another tree.

The borrowed root and any direct children opened from it expire when the callback returns. Closing the borrowed root is a no-op; owned child roots remain closeable after expiry.

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.

func (*DeliveryRoot) WriteFileExclusive added in v0.62.0 

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

WriteFileExclusive publishes one immutable root-relative file. It never replaces an existing final name; callers that use content-addressed names must treat os.ErrExist as a collision or an explicit idempotence decision.

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 DirectChildExistsError added in v0.61.0 

type DirectChildExistsError struct {
	Name string
}

DirectChildExistsError is returned when CreateDirectChildExclusive finds the name already present.

func (*DirectChildExistsError) Error added in v0.61.0 

func (e *DirectChildExistsError) Error() string

type LayoutState added in v0.60.5 

type LayoutState int

LayoutState classifies a pinned root's top-level queue layout. 

const (
	// LayoutInitialized: agents/ exists as a real directory — the minimum
	// evidence that this tree is (or is becoming) an AMQ queue.
	LayoutInitialized LayoutState = iota
	// LayoutEmpty: the root directory has no entries at all.
	LayoutEmpty
	// LayoutForeign: the root has entries but no agents/ directory — it is
	// some other directory, not a queue.
	LayoutForeign
)

type MailboxConfigAuthorization added in v0.49.7 

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

MailboxConfigAuthorization retains the exact config descriptor and content used to authorize mailbox repair. Callers must close it.

func (*MailboxConfigAuthorization) Close added in v0.49.7 

func (a *MailboxConfigAuthorization) Close() error

Close releases the retained config descriptor.

func (*MailboxConfigAuthorization) ConfiguredAgents added in v0.49.7 

func (a *MailboxConfigAuthorization) ConfiguredAgents() []string

ConfiguredAgents returns the roster bound to this authorization.

func (*MailboxConfigAuthorization) Verify added in v0.49.7 

func (a *MailboxConfigAuthorization) Verify() error

Verify confirms the retained descriptor, its content, and its current path still identify the exact config that authorized this operation.

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.

func InspectMailboxLayoutWithAuthorization added in v0.49.7 

func InspectMailboxLayoutWithAuthorization(root *DeliveryRoot, authorization *MailboxConfigAuthorization, effectiveAgents ...string) (MailboxInventory, error)

InspectMailboxLayoutWithAuthorization inventories root using the exact retained config capability supplied by the caller. effectiveAgents are treated as configured for callers whose roster includes implicit handles.

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.

func RepairMailboxLayoutForAgents added in v0.49.7 

func RepairMailboxLayoutForAgents(root *DeliveryRoot, agents []string) MailboxRepairResult

RepairMailboxLayoutForAgents validates and completes only the requested mailbox layouts using the same no-symlink, identity-pinned repair machinery as RepairMailboxLayout. A valid active config is still required, but the requested handles do not need to be listed in it.

func RepairMailboxLayoutForAgentsAuthorized added in v0.49.7 

func RepairMailboxLayoutForAgentsAuthorized(root, configRoot *DeliveryRoot, agents []string) MailboxRepairResult

RepairMailboxLayoutForAgentsAuthorized validates and completes only agents in root while taking initialization and roster authority from configRoot.

func RepairMailboxLayoutForAgentsWithAuthorization added in v0.49.7 

func RepairMailboxLayoutForAgentsWithAuthorization(root *DeliveryRoot, authorization *MailboxConfigAuthorization, agents []string) MailboxRepairResult

RepairMailboxLayoutForAgentsWithAuthorization repairs only agents using the exact retained config authorization previously used for roster validation.

func RepairMailboxLayoutForAgentsWithAuthorizationAndWriteGuard added in v0.62.0 

func RepairMailboxLayoutForAgentsWithAuthorizationAndWriteGuard(root *DeliveryRoot, authorization *MailboxConfigAuthorization, agents []string, writeGuard func() error) MailboxRepairResult

RepairMailboxLayoutForAgentsWithAuthorizationAndWriteGuard is the lease-bound variant used by launch Apply. writeGuard is revalidated before each directory mutation and durability sync; a revoked authority therefore stops the repair at the next owning write boundary.

func RepairMailboxLayoutForConfiguredAgentsWithAuthorization added in v0.49.7 

func RepairMailboxLayoutForConfiguredAgentsWithAuthorization(root *DeliveryRoot, authorization *MailboxConfigAuthorization, effectiveAgents []string) MailboxRepairResult

RepairMailboxLayoutForConfiguredAgentsWithAuthorization repairs an effective configured roster, including caller-owned implicit handles, while retaining the exact on-disk config authorization for mutation checks.

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

type PathSymlinkError added in v0.65.3 

type PathSymlinkError struct {
	Path string
}

PathSymlinkError names the component that was a symlink.

func (*PathSymlinkError) Error added in v0.65.3 

func (e *PathSymlinkError) Error() string

func (*PathSymlinkError) Unwrap added in v0.65.3 

func (e *PathSymlinkError) 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.