gabsurd

-module(gabsurd@checkpoint).
-compile([no_auto_import, nowarn_unused_vars, nowarn_unused_function, nowarn_nomatch, inline]).
-define(FILEPATH, "src/gabsurd/checkpoint.gleam").
-export([set/7, get/5]).
-export_type([checkpoint/0]).

-if(?OTP_RELEASE >= 27).
-define(MODULEDOC(Str), -moduledoc(Str)).
-define(DOC(Str), -doc(Str)).
-else.
-define(MODULEDOC(Str), -compile([])).
-define(DOC(Str), -compile([])).
-endif.

?MODULEDOC(
    " Checkpoint operations for the Absurd durable workflow system.\n"
    " Provides functions for setting and getting task checkpoint state.\n"
    "\n"
    " Checkpoints serve a dual purpose in Absurd:\n"
    "   1. They persist step results so completed steps are skipped on retry.\n"
    "   2. They extend the worker's claim lease by `extend_claim_by` seconds.\n"
    "\n"
    " The second behaviour is the primary lease extension mechanism — every\n"
    " checkpoint write keeps the worker's claim alive, so tasks with many\n"
    " short steps never time out.  For handlers that do a single long-running\n"
    " operation without checkpoints, see `gabsurd/task.extend_claim`.\n"
).

-type checkpoint() :: {checkpoint,
        binary(),
        binary(),
        binary(),
        bitstring(),
        gleam@time@timestamp:timestamp()}.

-file("src/gabsurd/checkpoint.gleam", 35).
?DOC(
    " Set a checkpoint for a task step.\n"
    "\n"
    " `extend_claim_by` is the number of seconds to extend the worker's claim\n"
    " lease. Pass your worker's `claim_timeout` value here so that every\n"
    " checkpoint write keeps the lease alive. Pass `0` to skip extension.\n"
).
-spec set(
    gabsurd@client:db(),
    binary(),
    bitstring(),
    binary(),
    gleam@json:json(),
    bitstring(),
    integer()
) -> {ok, nil} | {error, gabsurd@client:gabsurd_error()}.
set(Db, Queue_name, Task_id, Step_name, State, Owner_run_id, Extend_claim_by) ->
    gabsurd@client:exec(
        Db,
        gabsurd@sql:set_task_checkpoint_state(
            Queue_name,
            Task_id,
            Step_name,
            gleam@json:to_string(State),
            Owner_run_id,
            Extend_claim_by
        )
    ).

-file("src/gabsurd/checkpoint.gleam", 60).
?DOC(
    " Get a checkpoint for a task step.\n"
    " Returns `Ok(Some(checkpoint))` if found, `Ok(None)` if not found,\n"
    " or `Error(GabsurdError)` on database failure.\n"
).
-spec get(gabsurd@client:db(), binary(), bitstring(), binary(), boolean()) -> {ok,
        gleam@option:option(checkpoint())} |
    {error, gabsurd@client:gabsurd_error()}.
get(Db, Queue_name, Task_id, Step_name, Include_pending) ->
    case gabsurd@client:query_one(
        Db,
        gabsurd@sql:get_task_checkpoint_state(
            Queue_name,
            Task_id,
            Step_name,
            Include_pending
        )
    ) of
        {ok, Row} ->
            {ok,
                {some,
                    {checkpoint,
                        erlang:element(2, Row),
                        erlang:element(3, Row),
                        erlang:element(4, Row),
                        erlang:element(5, Row),
                        erlang:element(6, Row)}}};

        {error, not_found} ->
            {ok, none};

        {error, E} ->
            {error, E}
    end.