core

type AdmissionController ¶

type AdmissionController interface {
	Admit(exec Execution) error
}

AdmissionController decides whether an execution may proceed.

Admission happens BEFORE execution begins and may be influenced by backpressure, concurrency limits, or system health.

type AdmissionMode ¶

type AdmissionMode int

AdmissionMode defines what happens when execution capacity is exhausted.

const (
	// AdmissionHardReject rejects requests immediately when capacity is full.
	AdmissionHardReject AdmissionMode = iota

	// AdmissionSoftAllow allows execution on best-effort basis.
	AdmissionSoftAllow

	// AdmissionSoftAllowWithSignal allows execution but surfaces an explicit
	// admission failure signal to the caller.
	AdmissionSoftAllowWithSignal
)

type CancellationSource ¶

type CancellationSource int32

CancellationSource represents why an execution was cancelled.

const (
	SourceUnknown CancellationSource = iota
	SourceClientCancel
	SourceServerShutdown
	SourceDeadlineExceeded
	SourceAdmissionRejected
	SourceInternalError
)

func CancellationSourceOf(ctx context.Context) CancellationSource

type DeadlinePolicy ¶

type DeadlinePolicy int

DeadlinePolicy defines when deadlines are enforced.

const (
	// DeadlineBeforeAdmission counts queueing time toward deadlines.
	DeadlineBeforeAdmission DeadlinePolicy = iota

	// DeadlineAfterAdmission enforces deadlines only after execution begins.
	DeadlineAfterAdmission

	// DeadlineIgnoreAfterAdmission ignores the deadlines once admitted.
	DeadlineIgnoreAfterAdmission
)

type Execution ¶

type Execution struct {
	Ctx        context.Context
	Guarantees ExecutionGuarantees
}

Execution represents a single logical unit of work. This may correspond to: - a unary RPC - a streaming message - a batch element

type ExecutionGuarantees ¶

type ExecutionGuarantees struct {
	AdmissionMode  AdmissionMode
	DeadlinePolicy DeadlinePolicy
}

ExecutionGuarantees defines the complete behavioral contract for an execution.

Only fields that are actively enforced by the execution pipeline are included. AdmissionMode controls capacity gating. DeadlinePolicy controls deadline enforcement.

type Executor ¶

type Executor interface {
	Execute(exec Execution, fn func(context.Context) error) error
}

Executor is the only component allowed to run user code.

Responsibilities: - Enforce admission guarantees - Enforce cancellation precedence - Enforce deadline semantics - Enforce failure semantics - Ensure no goroutine leaks

Executor must be deterministic and race-safe

type FailureKind ¶

type FailureKind int

const (
	// No failures (successful processing)
	FailureNone FailureKind = iota

	// User handler returned an error
	FailureHandlerError

	// Context cancelled (client cancel, deadline)
	FailureContextCancelled

	// Backpressure rejected the message
	FailureBackpressure

	// Ordering system closed or violated
	FailureOrdering

	// Stream is shutting down
	FailureShutdown

	// Internal invariant violated (BUG)
	// This is NEVER retryable and ALWAYS terminal
	FailureInternal

	// Admission rejected
	FailureAdmission

	// Panic recovered
	FailurePanic
)

func Classify(err error) FailureKind

func (fk FailureKind) String() string

type Interceptor ¶

type Interceptor interface {
	Before(exec Execution)
	After(exec Execution, err error)
}

Interceptor allows observing and decorating execution.

IMPORTANT: - Interceptors MUST NOT modify ExecutionGuarantees - Interceptors MUST NOT block indefinitely - Interceptors MUST BE idempotent

Interceptors may: - record metrics - add tracing - log execution

type ShutdownCoordinator ¶

type ShutdownCoordinator interface {
	BeginShutdown()
	Done() <-chan struct{}
}

ShutdownCoordinator coordinates graceful shutdown.

Guarantees: - Shutdown is idempotent - Shutdown is race-free - Shutdown honors CancellationPrecedence