adk_invocation_ledger behaviour (erlang_adk v0.7.0)

View Source

Durable ownership and checkpoint ledger for resumable invocations.

Implementations must make create/claim/checkpoint/finish atomic. The opaque owner token and lease are both write fences: renew/checkpoint/finish validate the token, running phase, and explicit NowMs atomically. A token is expired when NowMs >= lease_until and cannot revive itself before a new claimant arrives. After takeover, writes from the previous coordinator fail with stale_owner.

Summary

Callbacks

checkpoint/6
claim/6
create/4
delete/2
finish/7
get/2
init/1
renew/5

Callbacks

checkpoint/6

-callback checkpoint(Handle :: term(),
                     InvocationId :: binary(),
                     OwnerToken :: binary(),
                     Checkpoint :: map(),
                     NowMs :: integer(),
                     LeaseMs :: pos_integer()) ->
                        ok | {error, stale_owner | lease_expired | not_found | term()}.

claim/6

-callback claim(Handle :: term(),
                InvocationId :: binary(),
                OwnerPid :: pid(),
                OwnerToken :: binary(),
                NowMs :: integer(),
                LeaseMs :: pos_integer()) ->
                   {ok, Invocation :: map()} | {error, not_found | completed | invocation_owned | term()}.

create/4

-callback create(Handle :: term(), InvocationId :: binary(), Metadata :: map(), Checkpoint :: map()) ->
                    ok | {error, already_exists | term()}.

delete/2

-callback delete(Handle :: term(), InvocationId :: binary()) ->
                    ok | {error, invocation_owned | not_found | term()}.

finish/7

-callback finish(Handle :: term(),
                 InvocationId :: binary(),
                 OwnerToken :: binary(),
                 Phase :: atom(),
                 Outcome :: term(),
                 Checkpoint :: map(),
                 NowMs :: integer()) ->
                    ok | {error, stale_owner | lease_expired | not_found | term()}.

get/2

-callback get(Handle :: term(), InvocationId :: binary()) ->
                 {ok, Invocation :: map()} | {error, not_found | term()}.

init/1

-callback init(Options :: map()) -> {ok, Handle :: term()} | {error, term()}.

renew/5

-callback renew(Handle :: term(),
                InvocationId :: binary(),
                OwnerToken :: binary(),
                NowMs :: integer(),
                LeaseMs :: pos_integer()) ->
                   ok | {error, stale_owner | lease_expired | not_found | term()}.