iii-hq/iii

iii-sdk-reference

Use when working with iii SDK APIs across Node.js, browser, Python, Rust, or Go: package installation, worker initialization, function registration, calling functions, observers and observer hooks, local dispatch, channels, logging, OpenTelemetry, and langu…

소스 보기

사용 방법

  1. 설치 명령을 복사하고 자신의 에이전트 환경에 설치하기 전에 소스 패키지를 확인하세요.
  2. 필요한 도구, 인증 정보, 지원 환경은 원본 문서에서 확인하세요.
  3. 입력과 원하는 산출물을 설명하고 출처와 결과를 대조하세요.
npx skills add https://github.com/iii-hq/iii --skill iii-sdk-reference

시작 전 확인

  • 설치에는 모델 구독, API 한도, 파일 접근 권한이 포함되지 않습니다.
  • 별점 수와 설치 수는 활동 지표이며 독립적인 품질·보안 검증이 아닙니다.
원본 Skill 문서

원본 저장소의 제목, 예시, 코드, 표, 링크, 이미지를 유지해 표시합니다.

SDK Reference

Use this skill for language-specific SDK details. Use iii-core-primitives for the common model and iii-error-handling for exception handling.

Install

bash
# TypeScript / Node.js
npm install iii-sdk

# Browser apps
npm install iii-browser-sdk

# Python
pip install iii-sdk

# Rust
cargo add iii-sdk

# Go
go get github.com/iii-hq/iii/sdk/packages/go/iii

Choose the SDK

SDKPackageBest forImportant caveat
Node.jsiii-sdkServer-side TypeScript/JavaScript workersSupports custom headers, Logger, OpenTelemetry
Browseriii-browser-sdkWeb apps and interactive UI callbacksConnect through the rbac-proxy worker's public port, never the engine port; keep secrets server-side
Pythoniii-sdkSync or async Python workersUse call_async inside async handlers
Rustiii-sdkHigh-performance tokio workersHandler error type should map into iii_sdk::Error
Gogithub.com/iii-hq/iii/sdk/packages/go/iiiGo servicesHandlers take (ctx, json.RawMessage); pass the handler's ctx to Call

Logger/OpenTelemetry, HTTP request/response types, stream, queue, and worker-connection types live in the helpers package, installed alongside the SDK: @iii-dev/helpers (Node, with submodules like /observability and /http) or iii-helpers (Python iii_helpers.*, Rust iii_helpers::*).

Common API Map

CapabilityNode / browserPythonRustGo
Connect workerregisterWorker(url, options?)register_worker(address, options?)register_worker(url, InitOptions)iii.RegisterWorker(url, opts...)
Register local functionregisterFunction(id, handler, options?)register_function(id, handler, **options)register_function("id", RegisterFunction::new(...))client.RegisterFunction(id, handler, opts...)
Call a functioncall({ function_id, payload })call(request) / call_async(request)call(CallRequest::new(id, payload))client.Call(ctx, iii.CallRequest{...})
Durable enqueueCallAction.Enqueue({ queue }){"type": "enqueue", "queue": name}CallAction::Enqueue { queue }iii.EnqueueAction(queue)
Fire and forgetCallAction.Void(){"type": "void"}CallAction::Voidiii.VoidAction()
Observe a functionobserve(source, target, options?); observe('fn::id', target)observe(source, target, options)observe(Source::function(id)..., target) / observe_with(.., ObserverOptions)client.Observe(iii.Source{...}, target, opts...) / client.ObserveFunction(id, target)
Function options for observers{ args_format, private, observable }args_format=, private=, observable=.args_format::<T>().private().observable(false)iii.FunctionOptions{ArgsFormat, Private, ...}
Observer hooks, one functioniii.onObserverAdded(id, h), onObserverRemoved(id, h), onObservationMatch(id, m), onObservationDeliver(id, h), or the same on the FunctionRef@iii.on_observer_added(id), @ref.on_observer_removed, ref.on_observation_match(m), ref.on_observation_deliver(h)on_observer_added_for(id, h), on_observer_removed_for(id, h), on_observation_match_for(id, m), on_observation_deliver_for(id, h), or function.on_observer_added(h)client.OnObserverAddedFor(id, h), OnObserverRemovedFor, OnObservationMatchFor, OnObservationDeliverFor, or ref.OnObserverAdded(h)
Observer hooks, every functioniii.onObserverAdded(h), iii.onObserverRemoved(h)@iii.on_observer_added, @iii.on_observer_removedon_observer_added(h), on_observer_removed(h)client.OnObserverAdded(h), client.OnObserverRemoved(h)
Match observers to callsonObservationMatch(id, (obs, call) => boolean) or onObservationMatch(id, { observer, call })on_observation_match(id, predicate) or on_observation_match(id, observer=, call=)Match::predicate(f) or Match::keys(observer_keys, call_keys)iii.MatchFunc(f) or iii.MatchKeys(observerKeys, callKeys)
Call through an observer (no metadata)call({ observer: obs, payload })call_async({"observer": obs, "payload": p})call(CallRequest::observer(&obs, payload))client.Call(ctx, iii.CallRequest{Observer: obs, Payload: p})
Current invocationcurrentInvocation()current_invocation()iii_sdk::current_invocation()iii.InvocationFromContext(ctx)
ChannelscreateChannel(iii) (iii-sdk/helpers)create_channel(iii) / create_channel_async(iii) (iii.helpers)iii_sdk::helpers::create_channel(&iii, None).awaitclient.CreateChannel(ctx, nil)

A call's metadata is any JSON value, delivered to the handler beside the payload. null (Python None, Rust Value::Null, Go json.RawMessage("null")) is the same as no metadata on every path, local or routed. A call through an observer takes no metadata: its target receives the observer's, and every SDK refuses one that names metadata with "a call through an observer takes no metadata; its target receives the observer's metadata".

Node.js

typescript
import { registerWorker } from "iii-sdk";
import { Logger } from "@iii-dev/helpers/observability";

const iii = registerWorker("ws://localhost:49134", {
  workerName: "node-worker",
  invocationTimeoutMs: 30000,
});

iii.registerFunction("users::lookup", async (input) => {
  new Logger().info("looking up user", { userId: input.userId });
  return { userId: input.userId, name: "Ada" };
});

Node supports custom WebSocket headers, Logger, OpenTelemetry options, call and observer metadata, channels, observers, and observer hooks. CallRequest, CallAction, ObserveRejection, and EngineSources are exported from the package root.

Browser

typescript
import { registerWorker, CallAction } from "iii-browser-sdk";

const iii = registerWorker("wss://api.example.com/worker?token=session-token");

const result = await iii.call({
  function_id: "backend::get-user",
  payload: { userId: "123" },
});

await iii.call({
  function_id: "analytics::track",
  payload: { event: "page_view" },
  action: CallAction.Void(),
});

Do not expose the private engine worker port to untrusted browsers; put the rbac-proxy worker in front of it (iii call compose::add worker=rbac-proxy). Browser workers cannot send custom WebSocket headers and must not hold backend secrets.

The browser call sends metadata, traceparent and baggage, and handlers receive metadata as their second argument. Browsers have no AsyncLocalStorage: iii.currentInvocation() is only known until the handler's first await, so read it first and wrap later calls in iii.withInvocation(inv, () => ...).

Python

python
from iii import InitOptions, register_worker
from iii_helpers.observability import Logger

iii = register_worker(
    address="ws://localhost:49134",
    options=InitOptions(worker_name="python-worker"),
)

def lookup_user(data):
    Logger().info("looking up user", {"userId": data["userId"]})
    return {"userId": data["userId"], "name": "Ada"}

iii.register_function("users::lookup", lookup_user)

Python handlers may be sync or async. Use await iii.call_async(request) inside async handlers, and iii.call(request) in sync contexts. HttpResponse (from iii_helpers.http) uses status_code, like the other helpers packages.

Rust

rust
use iii_sdk::{register_worker, InitOptions, RegisterFunction};
use serde_json::json;

let iii = register_worker("ws://127.0.0.1:49134", InitOptions::default());

iii.register_function(
    "users::lookup",
    RegisterFunction::new(|input: serde_json::Value| -> Result<serde_json::Value, iii_sdk::Error> {
        Ok(json!({ "userId": input["userId"], "name": "Ada" }))
    }).description("Look up a user"),
);

Rust supports typed handlers and schema extraction when input/output types derive schemars::JsonSchema. Add the otel feature when using OpenTelemetry helpers. A local call runs on the caller's task, and a sync handler (RegisterFunction::new) runs inline: make a blocking handler async or opt out with .local_dispatch(false). Rust has no overloading, so the client's per-function hook methods take a _for suffix (on_observer_added_for(id, hook)); a hook is an async closure or a type that implements AddedHook, RemovedHook, or DeliverHook.

Go

go
client := iii.RegisterWorker(iii.DefaultEngineURL, iii.WithNamespace("orders"))

client.RegisterFunction("users::lookup", func(ctx context.Context, data json.RawMessage) (any, error) {
	var in struct {
		UserID string `json:"userId"`
	}
	if err := json.Unmarshal(data, &in); err != nil {
		return nil, err
	}
	return map[string]string{"userId": in.UserID, "name": "Ada"}, nil
})

Per-invocation metadata rides on ctx (iii.MetadataFromContext(ctx)). Inside a handler, pass its ctx to client.Call so the call carries the caller and the observe depth. RegisterFunction returns (*iii.FunctionRef, error); iii.Identity is a handler that returns its input, for event sources.

Observers and local dispatch

  • observe(source, target, options?) is in every SDK: when the source function runs, the target

runs. HTTP routes, database changes, and queue topics are observers of http::on-request, database::on-row-changed, and queue::on-message. Details and examples per language: iii-observe.

  • registerFunction returns a FunctionRef with the hook methods, isObserved(call?) and

observers() (Python is_observed(call=None), Rust is_observed() / is_observed_for(&call), Go ref.IsObserved() / ref.IsObservedFor(call)). With a call, on a function whose onObservationMatch uses keys, isObserved looks up the call's keys.

  • A call to a function the same worker registered runs in-process once the engine confirmed it.

Force the engine path per call with dispatch: 'remote' (Node, browser, Python "dispatch": "remote"), Rust CallRequest::new(..).dispatch(Dispatch::Remote), Go Dispatch: iii.DispatchRemote; or per function with localDispatch: false (local_dispatch=False, .local_dispatch(false), LocalDispatch: &off).

  • Against an engine without observe.v2, a function that declares args_format, private, or

observable: false, or sets onObservationMatch or onObservationDeliver, stays unregistered and the SDK logs UNSUPPORTED once; everything else works.

  • The default capture is [input, output, caller]; metadata is opt-in.

Channels

  • Use channels for binary data, large payloads, or streaming transfer between workers.
  • Pass readerRef or writerRef through a function payload.
  • Reconstruct readers/writers from refs in consumers when the SDK requires it.
  • A close tells the reader the stream is complete, so a writer that fails must abort instead: Node

writer.stream.destroy() (no argument), Rust drop the writer without close(), Go Close after a failed Write. Go, Python and browser writers have no other abort call. A crash or a lost connection aborts on its own; a writer left open keeps the reader waiting until its process exits.

  • On an abort the read errors after the data already sent (Rust Err, Node stream 'error',

browser rejection, Python ConnectionError, Go non-EOF error): treat it as an incomplete transfer. A writer whose socket never opened (it failed before its first write or, in Node, right after one, while the socket was still connecting) never reached the engine, so also check the producer's result.

Namespaces

A worker belongs to one namespace: options.namespace (InitOptions.namespace) → the III_NAMESPACE environment variable → the engine's default. Compose sets III_NAMESPACE to its daemon's namespace (iii compose -n dev ...) for every worker it starts, so a whole project lands in one namespace without any code change. Routing is strict: a function is only reachable in the namespace it registered in.

  • iii.call({ function_id }) resolves in the calling worker's namespace. Calls to your own

functions and to other workers declared in the same worker-compose.yaml need no namespace.

  • Engine-owned functions register in default: engine::*, configuration::*, and the

observability::* sources. engine::* and configuration::* resolve there implicitly (since 0.24.5); for the others pass namespace: "default" on the call, or on an observe source, when your worker runs in a Compose namespace.

  • observe resolves its source in the worker's namespace, so an observer of http::on-request

binds to the http worker of the same project.

  • Never prefix a function id with a namespace. The id stays orders::validate; the namespace is a

separate field.

  • From the CLI, iii call -n dev orders::validate ... selects the namespace; omitting -n

resolves in default.

typescript
// Same-project worker: no namespace
await iii.call({ function_id: "orders::validate", payload: order });

// Engine-owned configuration worker: resolves in `default` without a namespace;
// naming it explicitly is equivalent
const cfg = await iii.call({
  function_id: "configuration::get",
  namespace: "default",
  payload: { id: "orders" },
});
python
cfg = await iii.call_async(
    {"function_id": "configuration::get", "namespace": "default", "payload": {"id": "orders"}}
)
rust
let cfg = iii
    .call(CallRequest::new("configuration::get", json!({ "id": "orders" })).namespace("default"))
    .await?;

When to Use

  • Use this skill for package names, SDK exports, initialization options, browser security constraints,

channel API details, and language-specific syntax.

  • Use this when a task asks for Python, Rust, or Go examples and the issue is SDK syntax rather

than iii architecture.

Boundaries

  • For the common Worker/Function/Observer model, built-in source functions, and invocation mode

decisions, use iii-core-primitives.

  • For the observe model, filters, observer hooks, event sources, and upgrading 0.25 code, use

iii-observe.

  • For deployment config, engine-owned workers, RBAC (rbac-proxy), and ports, use

iii-engine-config.

  • For retryability and exception classes, use iii-error-handling.
같은 저장소의 Skills

더 많은 Skills

모든 Skills