spi/me.ahoo.wow.spi.ledger

Package-level declarations

Types

The failure ledger of one service (documentation/designs/04-subscriptions.md §2).

class LedgerAggregate @InternalWowApi constructor(val context: String, val name: String, val tenantId: String, val id: String)

A parked aggregate as the ledger's commands name it: the aggregate name of context, its tenantId and id (the shape of an entry on the operator routes, /wow/ops/parked).

LedgerEntry

@InternalWowApi

class LedgerEntry @InternalWowApi constructor(val service: String, val context: String, val subscription: String, val aggregate: LedgerAggregate, val fromVersion: Int, val fromPosition: Long? = null, val reason: String, val failedAt: Long, val retries: Int = 0, val retryAt: Long? = null, val retrySpec: LedgerRetrySpec, val recoverable: String = UNKNOWN, val request: String? = null, val status: String, val nextRetryAt: Long? = null, val recordedAt: Long)

subscription of service parks aggregate, as its ledger holds it now (FailureLedger's entry with the retry spec it is retried by); the entry's command topic is context's, the context of the subscription.

LedgerRequest

enum class LedgerRequest : Enum<LedgerRequest>

An operator's request on a parked entry, left in the ledger by a node that does not own the entry's partition: the owner takes it (ParkedAmendment.TakeRequest) and runs it.

LedgerResolution

@InternalWowApi

class LedgerResolution @InternalWowApi constructor(val service: String, val context: String, val subscription: String, val aggregate: LedgerAggregate, val failedAt: Long? = null, val outcome: String, val resolvedAt: Long)

subscription of service no longer parks aggregate, as of resolvedAt (epoch milliseconds): the parking that failed at failedAt (null when the service did not know it) came to outcome: RETRIED (handled again), SKIPPED, RESOLVED (gone from the ledger, by an automatic retry or another node's action) or NOT_PARKED (an operator's action found nothing parked).

LedgerRetrySpec

@InternalWowApi

class LedgerRetrySpec @InternalWowApi constructor(val maxRetries: Int, val initialBackoff: String, val claimTtl: String, val applied: Boolean = false)

The retry spec a parked entry is retried by: at most maxRetries automatic retries, the first initialBackoff after the failure, each claiming the entry for claimTtl (durations); applied when an operator applied it, rather than the subscription's.

ParkedAggregate

class ParkedAggregate @InternalWowApi constructor(val subscription: SubscriptionId, val ref: AggregateRef, val partition: Int, val fromVersion: Int, val reason: String, val failedAt: Long, val fromPosition: Long? = null, val retries: Int = 0, val retryAt: Long? = null, val retrySpec: ParkedRetrySpec? = null, val recoverable: Recoverable = Recoverable.UNKNOWN, val request: LedgerRequest? = null, val nextAttemptAt: Long? = null, val revision: Long = 0)

One parked aggregate: subscription stopped handling ref, in its source's partition, at its stream fromVersion, at failedAt (epoch milliseconds), because of reason. The owner of partition retries it.

ParkedAmendment

@WowSpi

sealed interface ParkedAmendment

A change of a parked entry's retry state (FailureLedger.amend), or, for Restate alone, of why it is parked and its retry state at once.

ParkedRetrySpec

class ParkedRetrySpec @InternalWowApi constructor(val maxRetries: Int = DEFAULT_MAX_RETRIES, val initialBackoff: Duration = DEFAULT_INITIAL_BACKOFF, val claimTtl: Duration = DEFAULT_CLAIM_TTL)

How a parked entry is retried over the long horizon (9.x RetrySpec): at most maxRetries automatic retries, the first initialBackoff after the failure and each next one twice as long after the previous one started; claimTtl is how long a retry's claim on the entry holds before another retry may start, such as on the partition's next owner: it cancels nothing, the retry runs on. A maxRetries of 0 turns automatic retries off.

Recoverable

enum class Recoverable : Enum<Recoverable>

What an operator marked a parked entry (9.x RecoverableType); only UNRECOVERABLE stops its automatic retries.

Functions

amended

fun ParkedAggregate.amended(amendment: ParkedAmendment): ParkedAggregate?

This entry with amendment applied at the next revision, or null when the amendment names a revision read that the entry is no longer at: the reference semantics of FailureLedger.amend, for a backend that changes the entry in memory. Every amendment but a ParkedAmendment.Schedule and a ParkedAmendment.TakeRequest clears ParkedAggregate.nextAttemptAt, so the owner looks at the entry again on its next scan.

dueIn

fun ParkedAggregate.dueIn(partitions: Collection<Int>, now: Long): Boolean

Whether this entry is due at now in one of partitions (FailureLedger.due): the reference semantics, for a backend that filters in memory.

placedAs

fun ParkedAggregate.placedAs(entry: ParkedAggregate): ParkedAggregate

This entry where entry parks the aggregate (its partition, from version and position) and why (its reason and failure time), with this entry's retry state, at the next revision and no longer scheduled: the reference semantics of a FailureLedger.repark, and of a FailureLedger.park that replaces an entry.