Control durability guarantees

Golem provides a set of functions components can call to control details of the durable execution engine.

General concepts

The high-level SDKs let applications control idempotence, define atomic regions, commit the oplog, and change retry policies (discussed in the next page).

All these features are regional - they can be changed for a section of the code within a single exported function.

Custom durable operations

Applications normally rely on Golem’s built-in durability and should not call the low-level golem:durability@1.6.0 interface. It is intended for SDK and library authors who need to turn an otherwise raw operation into one logical durable call.

A custom durable operation has a replay-stable UUID, a semantic request, and one typed response. The executor allocates the UUID synchronously when the operation begins. The UUID is independent of the request value, so a generator with no input is distinct from another concurrent call of the same generator.

1. begin-custom-durable-invocation takes the function name, typed request, and function type. It returns live(live-invocation) for a new or incomplete operation, or replayed(recorded-response) for an operation that already completed.
2. On the live path, keep the returned resource alive while performing the operation’s host effects. Host calls initiated while it is active are recorded as replay-inert observational entries owned by the custom operation.
3. Finish consumes the live resource and records the operation’s complete success or failure result. On replay, decode and return the recorded response without executing the operation body.

Golem derives the UUID from the top-level idempotency key, the parent custom invocation when nested, and a deterministic ordinal in that logical parent’s namespace. Child operations do not shift later root identities when a completed parent is skipped during replay. The function metadata and request are recorded and validated independently.

The live invocation is an affine resource: it can be finished only once. Dropping it without finishing removes observational ownership but does not write a matching End entry. Recovery therefore treats the custom operation as incomplete and retries its whole body.

If a live attempt traps before it is finished, recovery retries the whole custom operation, not individual effects inside it. Library authors must therefore choose an appropriate function type and make repeated attempts safe, for example with an external idempotency key or transactional API.

Requests, responses, operation names, and observational host calls can be visible to oplog search, logs, metrics, and other observability tooling. Record useful names and schemas, but redact secrets and avoid putting unnecessary or unbounded payloads into observable values.

Use the SDK combinator for this lifecycle instead of managing the affine resource directly: golem_rust::durability::Durability::run* in Rust, durable in TypeScript, Durability.wrap/wrapInfallible in Effect TypeScript, DurabilityApi.durable/durableAsync in Scala, or @api.durable/durable_async in MoonBit. Each combinator starts the invocation before evaluating the body, skips the body on replay, finishes after the complete live body returns, and drops any live resource left unfinished.

In Effect TypeScript, Durability.wrap records both successes and typed failures described by its error schema. Defects, interruption, and response-encoding failures leave the live invocation unfinished. Durability.wrapInfallible accepts an Effect with no typed error channel.

Idempotence mode

Golem assumes that HTTP requests are idempotent by default. This means that in case of a failure, if the system cannot determine whether the request successfully reached the target or not, it will be retried.

import {withIdempotenceMode} from "@golemcloud/golem-ts-sdk"
 
const result: string = withIdempotenceMode(false, () => {
  // this closure runs with idempotence mode disabled
  return "hello"
})

import { Effect } from "effect"
import { Durability } from "@golemcloud/effect-golem"
 
const result = Durability.withIdempotenceMode(
  false,
  Effect.succeed("hello"),
)

use golem_rust::with_idempotence_mode;
 
let result: &str = with_idempotence_mode(false, || {
  // this block runs with idempotence mode disabled
  "hello"
});

import golem.Guards
 
import scala.concurrent.Future
 
val result: Future[String] =
  Guards.withIdempotenceMode(false) {
    // this block runs with idempotence mode disabled
    Future.successful("hello")
  }

let result : String = @api.with_idempotence_mode(false, fn() {
  // this callback runs with idempotence mode disabled
  "hello"
})

With disabled idempotence mode, in case Golem cannot determine if the request was sent or not, it won’t retry it, but the agent will fail.

Atomic regions

By default, side effects are persisted and retried one by one. It is possible to group them together into atomic regions, in which case the execution is retried for some reason (the agent failed or interrupted within the region), all the side effects will be reexecuted.

import {atomically} from "@golemcloud/golem-ts-sdk"
 
const result: [string, string] = atomically<[string, string]>(() => {
  const firstResult: string = firstSideEffect()
  const secondResult: string = secondSideEffect(firstResult)
  return [firstResult, secondResult]
})

import { Effect } from "effect"
import { Durability } from "@golemcloud/effect-golem"
 
const result = Durability.atomically(
  Effect.gen(function* () {
    const first = yield* firstSideEffect
    const second = yield* secondSideEffect(first)
    return [first, second] as const
  }),
)

use golem_rust::atomically;
 
let result = atomically(|| {
    let first_result = first_side_effect();
    let second_result = second_side_effect(&first_result);
    (first_result, second_result)
});

import golem.Guards
 
import scala.concurrent.Future
 
val result: Future[(String, String)] =
  Guards.atomically {
    val firstResult = firstSideEffect()
    val secondResult = secondSideEffect(firstResult)
    Future.successful((firstResult, secondResult))
  }

let result : (String, String) = @api.with_atomic_operation(fn() {
  let first_result : String = first_side_effect()
  let second_result : String = second_side_effect(first_result)
  (first_result, second_result)
})

Commit oplog

import { oplogCommit } from '@golemcloud/golem-ts-sdk';
 
// Ensure oplog is replicated to 3 replicas before proceeding
oplogCommit(3);

import { Durability } from "@golemcloud/effect-golem"
 
const committed = Durability.oplogCommit(3)

use golem_rust::oplog_commit;
 
// Ensure oplog is replicated to 3 replicas before proceeding
oplog_commit(3);

import golem.HostApi
 
// Ensure oplog is replicated to 3 replicas before proceeding
HostApi.oplogCommit(3)

// Ensure oplog is replicated to 3 replicas before proceeding
@api.oplog_commit(3)