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:
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/kotlinakter 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.
| Flag | Default | Description |
|---|---|---|
--lang | Required | rust, go, python, swift or kotlin. |
--out | Required | Folder that receives the generated package. |
--entry | src/app.layer.ts | Module exporting app = { actors, layer }. |
--name | Name of --out | Package name of the client, in lowercase letters, digits, - and _. |
--runtime-path | Required | Checkout 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:
SaleStateis one exhaustive union with a variant per state, so amatchorswitchover it checks every state. - Types: a struct for each object schema and an enum for each union of string literals. A set of
_tagobjects, such as a channel event, becomes a tagged union. - Callers:
SaleCallerhas 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 asStateNotAllowedError. A defect, an interruption or a transport failure can end any call too. - Handle:
SaleClientbinds a runtime client, a key and a caller. It hascreateandensurewhen the actor takes a creation input, andwarm. It has one async method per command and per query, and a live stream per query and for the state. It hasjoinandmembersfor the channel, and a stream method perAkter.httpStreamjob 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.
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))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})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))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.