Skip to content

Polyglot clients

akter codegen compiles your app’s contracts into a typed client for Rust, Go, Python, Swift or Kotlin. The client calls the same /rpc endpoint as @akterjs/client, so it works against akter dev and Akter Cloud without change.

Generate a client⁠

To generate a client, run akter codegen with a language, an output folder and the matching runtime checkout:

Terminal
npx @akterjs/cli codegen --lang rust --out ./crates/sale-client --runtime-path ../akter/sdks/rust
npx @akterjs/cli codegen --lang go --out ./internal/saleclient --runtime-path ../akter/sdks/go
npx @akterjs/cli codegen --lang python --out ./sale_client --runtime-path ../akter/sdks/python
npx @akterjs/cli codegen --lang swift --out ./SaleClient --name sale-client --runtime-path ../akter/sdks/swift
npx @akterjs/cli codegen --lang kotlin --out ./sale-client --runtime-path ../akter/sdks/kotlin

akter codegen loads the module that --entry names and reads the published contracts of its actors. It writes one package into --out and lists the generated files in .akter-codegen.json. A later run deletes the files that it no longer generates. It never writes through a symbolic link inside --out, and it never deletes through one that leaves --out. Generation refuses contracts that a client cannot carry, such as an actor without callers or a command named create, and names the reason. Run it again after every contract change. Generation needs no network.

FlagDefaultDescription
--langRequiredrust, go, python, swift or kotlin.
--outRequiredFolder that receives the generated package.
--entrysrc/app.layer.tsModule exporting app = { actors, layer }.
--nameName of --outPackage name of the client, in lowercase letters, digits, - and _.
--runtime-pathRequiredCheckout of the language runtime under sdks/ that the client uses.

What the client contains⁠

The client takes every name from your contract. For an actor named Sale, it contains these parts:

  • State union: SaleState is one exhaustive union with a variant per state, so a match or switch over it checks every state.
  • Types: a struct for each object schema and an enum for each union of string literals. A set of _tag objects, such as a channel event, becomes a tagged union.
  • Callers: SaleCaller has one variant per declared caller, and each variant carries its typed principal.
  • Errors: each member with declared errors gets its own error union, such as SaleBuyError. Any call can also fail with a hosted error such as StateNotAllowedError. A defect, an interruption or a transport failure can end any call too.
  • Handle: SaleClient binds a runtime client, a key and a caller. It has create and ensure when the actor takes a creation input, and warm. It has one async method per command and per query, and a live stream per query and for the state. It has join and members for the channel, and a stream method per Akter.httpStream job binding.

Optional fields stay absent on the wire when you leave them unset. Nullable fields send null.

Call an actor⁠

Each language builds a runtime client from the app URL, then a handle from a key and a caller.

python
from akter_client import AkterClient
from sale_client import SaleBuyerCaller, SaleBuyerPrincipal, SaleBuyInput, SaleClient

async with AkterClient("http://127.0.0.1:4000") as client:
    sale = SaleClient(client, "spring", SaleBuyerCaller(principal=SaleBuyerPrincipal(id="b1")))
    order = await sale.buy(SaleBuyInput(quantity=2))
go
client, err := akter.NewClient("http://127.0.0.1:4000")
sale := saleclient.NewSaleClient(client, "spring", saleclient.SaleCallerBuyer{Principal: saleclient.SaleBuyerPrincipal{ID: "b1"}})
order, err := sale.Buy(ctx, saleclient.SaleBuyInput{Quantity: 2})
swift
let client = AkterClient(url: url)
let sale = SaleClient(client: client, key: "spring", caller: .buyer(SaleBuyerPrincipal(id: "b1")))
let order = try await sale.buy(SaleBuyInput(quantity: 2))
kotlin
AkterClient(url).use { client ->
    val sale = SaleClient(client, "spring", SaleCaller.Buyer(SaleBuyerPrincipal(id = "b1")))
    val order = sale.buy(SaleBuyInput(quantity = 2))
}

The Rust client follows the same shape with async fn methods that return Result, and Stream values for live updates.

Live updates arrive once and in order⁠

Live queries, the state stream and channels each open one WebSocket. Every live update carries the actor’s commit version. The runtime applies an update only when its version is newer than the last one it applied. A lost socket reconnects with backoff from 50 ms up to 5 s. The reconnect never repeats or reorders updates. A typed failure ends the stream and never retries.

Every language passes the same transcript⁠

The harness in packages/codegen/tests compiles one multi-state Sale actor for all five languages. It builds each client with its real toolchain and runs the same 27 steps against InMemoryRpc or akterd --local. Each transcript must equal one golden file.