Sluice SDK -- Cross-SDK Parity

API comparison

Outcome values

Error types

Configuration environment variables

All three SDKs read the same environment variables with the same defaults:

Language-idiomatic patterns

Python -- async context manager

The context manager handles acquire-retry-release automatically. The async with block guarantees release even if an exception is raised.

async with slot("openai#gpt-4o#requests", timeout=10.0) as result:
    response = await call_openai(prompt)

TypeScript -- handle with try/finally

slot() returns a SlotHandle that must be released in a finally block. With TypeScript 5.2+, await using provides automatic disposal.

// Manual release
const handle = await slot("openai#gpt-4o#requests", { timeout: 10 });
try {
  const response = await callOpenAI(prompt);
} finally {
  await handle.release();
}

// Automatic disposal (TS 5.2+)
await using handle = await slot("openai#gpt-4o#requests", { timeout: 10 });
const response = await callOpenAI(prompt);

Go -- callback or defer

WithSlot is the safest because release is handled internally. Slot returns a handle that must be released with defer.

// Callback (recommended)
err := sluice.WithSlot(ctx, "openai#gpt-4o#requests", 10*time.Second,
    func(ctx context.Context) error {
        _, err := callOpenAI(ctx, prompt)
        return err
    },
)

// Handle + defer
handle, err := sluice.Slot(ctx, "openai#gpt-4o#requests", 10*time.Second)
if err != nil { return err }
defer handle.Release(ctx)

Common gotchas

Python

• All functions are async. You must await them or use async with.
• slot() is an async context manager, not a regular function that returns a handle. Do not try to await slot(...) without async with.
• penalize is best-effort and does not raise on failure.

TypeScript

• All functions return promises. Do not forget await.
• slot() returns a SlotHandle, not a context manager. You must call release() explicitly (or use await using).
• penalize is best-effort and silently swallows errors.
• The release() function on AcquireResult is idempotent -- calling it twice is safe.

Go

• All functions require a context.Context as the first argument, including Release.
• Penalize returns an error (unlike Python/TS which swallow it). Check or explicitly discard with _ =.
• WithSlot internally defers release, so the callback's context is the original context (not a derived one).
• The factor argument to Penalize is required (not optional like in Python/TS).
• SlotTimeout is a value type (SlotTimeout{}), not a pointer. Use errors.As(err, &timeout) with a value variable.