Crate aster_forge_tasks

Expand description

Shared background task primitives for Aster services.

This crate owns product-neutral task mechanics: step state transitions, typed payload/result serialization, retry classification, erased task-spec adapters, registry generation, runtime worker loops, lease guards, heartbeat loops, lane claiming, dispatch aggregation, drain loops, and task artifact temporary-directory helpers. It deliberately does not own database entities, SeaORM repositories, product task kind enums, runtime configuration, metrics labels, or concrete task implementations. Product crates keep those boundaries and register their specs and storage adapters explicitly.

Macros§

runtime_task_registry: Generates product-local runtime task metadata lookup functions.
task_registry: Generates a product-local static task registry.

Structs§

BackgroundTaskDispatchBackoff: Adaptive idle backoff for background task dispatch workers.
BackgroundTaskDispatchIteration: Activity summary returned by one dispatch iteration.
BackgroundTaskRuntimeComponent: Runtime component that owns spawned background task handles.
BackgroundTaskRuntimeComponentFromShutdown: Runtime builder component that spawns background tasks from the shared shutdown token.
BackgroundTaskRuntimeDefinitionsComponent: Runtime component that owns spawned task handles and registers task definitions.
BackgroundTaskRuntimeDefinitionsComponentFromShutdown: Runtime builder component that spawns background tasks and registers task definitions.
BackgroundTasks: Shutdown-aware collection of spawned background workers.
ClaimedTask: Successfully claimed task metadata.
ClaimedTaskExecutionConfig: Configuration for the shared claimed-task execution lifecycle.
DispatchStats: Aggregate counters returned by a background task dispatch pass.
LeasedScheduledRuntimeConfig: Configuration for a leased group of scheduled runtime tasks.
PeriodicTask: Configuration for one periodic runtime task worker.
RecordedTaskHooks: Product callbacks used by panic-protected recorded task iterations.
RuntimeTaskDefinition: Product-owned runtime task metadata registered with Forge helpers.
ScheduledPeriodicTask: Configuration for one scheduled periodic runtime task worker.
ScheduledRuntimeTaskGroup: Lease-scoped task group used by product registration closures.
ScheduledTaskCatalogEntry: One scheduled runtime task entry registered by a product runtime.
ScheduledTaskClaim: Claimed scheduled task firing.
ScheduledTaskClaimRenewal: Renewal update for a claim whose task body is still running.
ScheduledTaskClaimRequest: Request to atomically claim one due scheduled task firing.
ScheduledTaskCompletion: Completion update for a claimed scheduled task.
TaskClaimCandidate: Candidate task selected for compare-and-swap claiming.
TaskDedupeKey: Validated task dedupe key.
TaskDispatchOutcome: Counters returned by one claimed task execution.
TaskExecutionContext: Task execution context passed to product task implementations.
TaskLaneConfig: Product-owned dispatch lane configuration.
TaskLease: Persisted processing lease assigned when a task is claimed.
TaskLeaseGuard: Shared in-memory lease guard observed by task code and heartbeat code.
TaskPermanentFailure: Failure update passed to product storage after a task exhausts automatic retry.
TaskRetryUpdate: Retry update passed to product storage after an automatically retryable failure.
TaskSpecAdapter: Zero-sized adapter from typed task specs to object-safe task specs.
TaskStepInfo: Serialized task step shown in task APIs.
TaskStepSpec: Static step definition used to create initial task steps.

Enums§

BackgroundTaskDispatchTrigger: Reason a dispatch loop is about to run an iteration.
RuntimeTaskName: Runtime task name stored in product payloads.
TaskCoreError: Error returned by shared task helpers before product-level mapping.
TaskRetryClass: Retry behavior selected after a task failure.
TaskStepStatus: Runtime status for a task step.

Constants§

BACKGROUND_TASKS_COMPONENT: Stable component name used for background task workers.
BACKGROUND_TASKS_SHUTDOWN_PHASE: Stable shutdown phase name for background task workers.
BACKGROUND_TASK_DISPATCH_ERROR_BACKOFF_CAP: Minimum backoff used after a dispatch iteration returns an error.
BACKGROUND_TASK_SHUTDOWN_GRACE: Default grace period used when shutting down background workers.
TASK_DEDUPE_KEY_MAX_LEN: Maximum length for persisted task dedupe keys.

Traits§

BackgroundTaskSpec: Product-owned typed task specification.
ClaimableTaskRecord: Minimal task row view required by generic claim logic.
ClaimedTaskExecutionStore: Product hooks required by the shared claimed-task execution lifecycle.
ErasedBackgroundTaskSpec: Object-safe task spec used by registries and dispatchers.
ExecutableTaskRecord: Minimal read-only view required to execute a claimed task.
RegisteredRuntimeTaskKind: Lookup contract implemented by product-owned runtime task enums.
ScheduledTaskStore: Persistence contract used by scheduled task runners.
TaskClaimStore: Product storage adapter required by generic lane claiming.
TaskHeartbeatStore: Product storage adapter used by the generic heartbeat loop.
TaskRecord: Minimal read-only view over a persisted task row.

Functions§

available_lane_capacity: Returns remaining lane capacity after subtracting currently active tasks.
background_task_component: Creates the background task runtime component used by product entrypoints.
background_task_component_from_shutdown: Creates a runtime component that spawns background tasks from the shared shutdown token.
background_task_component_with_definitions: Creates the background task runtime component with product task definitions.
background_task_component_with_definitions_from_shutdown: Creates a task-definition component that spawns workers from the shared shutdown token.
boxed_task_future: Converts an operation into a boxed future.
claim_due_for_lane: Claims due tasks for a single lane using a product storage adapter.
claim_limit_to_u64: Converts a lane limit into the u64 shape used by database query limits.
cleanup_runtime_temp_root: Cleans the short-lived runtime temporary directory under temp_root.
cleanup_task_temp_dir_for_lease_in_root: Cleans the token-scoped temporary directory for one claimed task lease.
cleanup_task_temp_dir_for_task_in_root: Cleans every temporary artifact directory for one persisted task id.
cleanup_temp_dir: Cleans a temporary directory tree, logging failures instead of returning them.
decode_payload_as: Decodes a task payload as the typed payload for S.
decode_result_as: Decodes a task result as the typed result for S.
default_task_retry_delay_secs: Default retry delay used by Aster task dispatchers.
dispatch_lanes: Runs lane dispatchers concurrently and aggregates lane statistics.
drain_dispatcher: Drains a dispatcher until it has no claimed work and no active processing tasks.
effective_dispatch_base_interval: Returns the effective dispatch base interval, enforcing a one-second minimum.
effective_dispatch_max_interval: Returns the effective maximum dispatch interval.
effective_jitter_cap: Returns the effective jitter cap for one periodic interval.
evaluate_heartbeat_result: Evaluates one persisted heartbeat result and updates the in-memory lease guard.
initial_task_steps_from_specs: Creates initial task step state from static specs.
mark_active_step_failed: Marks the active step failed, or the last pending step when no step is active.
next_scheduled_run_at: Computes the next run timestamp after a completed scheduled task firing.
periodic_sleep_duration: Returns a periodic delay with bounded positive jitter.
prepare_task_temp_dir_in_root: Prepares the token-scoped temporary directory for one claimed task lease.
process_claimed_task: Runs one claimed task through heartbeat, processing, retry, and failure handling.
run_claimed_task_batch: Runs an already claimed task batch and aggregates task execution outcomes.
run_claimed_task_batch_with_store: Runs a claimed task batch using the shared lifecycle and aggregates counters.
run_dispatch_worker: Runs a wakeable dispatch loop with adaptive idle backoff.
run_leased_background_tasks: Runs a singleton background task group behind a Forge runtime lease.
run_periodic_task: Runs a periodic task until shutdown.
run_recorded_task_iteration: Runs one panic-protected task iteration and records its outcome.
run_scheduled_claim_renewal_loop: Renews one owned scheduled task claim until stopped or the claim is lost.
run_scheduled_periodic_task: Runs a scheduled periodic task until shutdown.
run_task_heartbeat_loop: Runs heartbeat updates until stopped, the persisted lease is lost, or renewal times out.
run_with_concurrency_limit: Runs item handlers with a bounded number of in-flight futures.
scheduled_claim_renew_interval: Derives the claim renewal tick from the claim TTL.
scheduled_task_dedupe_key: Builds a stable dedupe key for one scheduled task firing.
serialize_payload: Serializes a typed task payload.
serialize_result: Serializes a typed task result.
set_task_step_active: Marks a task step active.
set_task_step_skipped: Marks a task step skipped.
set_task_step_succeeded: Marks a task step succeeded.
spawn_task_heartbeat_with_interval: Spawns a heartbeat worker with the provided interval.
stop_task_heartbeat: Stops and awaits a heartbeat worker.
task_lease_expires_at: Returns the persisted lease expiry timestamp for a claim or heartbeat update.
task_lease_renewal_timeout: Returns the in-memory renewal timeout used to stop unsafe workers.

Type Aliases§

Result: Result type returned by shared task helpers.
TaskProcessFuture: Boxed future returned by task processors.