Skip to content

Latest commit

 

History

History

examples

Folders and files

README.md

Examples

Small, complete programs, one directory per language. CI compiles every example (mise run examples:check) and runs it (mise run examples:run), and the package READMEs quote them, so an example that no longer builds or no longer works fails the PR.

One example per call type

Each file is short, starts with a comment saying what it shows, and is run by mise run examples:run against the conformance replay server with the case of the same name in conformance/cases/examples/. The run writes examples-results.json (language, example, status, duration_ms, commit per example) and fails if any example fails. Run one language with python3 tools/run-examples.py --lang go, one call type with --only retries. examples.toml lists the call types, the credentials each one uses and how each language is built and run.

Call type Rust TypeScript Go Python Java C# Swift
unary-get: One unary call, GET /v1/me unary-get.rs unary-get.ts unary-get unary_get.py UnaryGet.java UnaryGet.cs UnaryGet.swift
list-pagination: A paged list, every item then one page by hand list-pagination.rs list-pagination.ts list-pagination list_pagination.py ListPagination.java ListPagination.cs ListPagination.swift
stream-sse: The account's events over server-sent events stream-sse.rs stream-sse.ts stream-sse stream_sse.py StreamSse.java StreamSse.cs StreamSse.swift
stream-socket: The same events over the /v1/ws socket stream-socket.rs stream-socket.ts stream-socket stream_socket.py StreamSocket.java StreamSocket.cs none yet
typed-error: A refused call as a typed error with a code typed-error.rs typed-error.ts typed-error typed_error.py TypedError.java TypedError.cs TypedError.swift
auth-token: A fixed API token from the environment auth-token.rs auth-token.ts auth-token auth_token.py AuthToken.java AuthToken.cs AuthToken.swift
auth-custom-token: A token provider of your own auth-custom-token.rs auth-custom-token.ts auth-custom-token auth_custom_token.py AuthCustomToken.java AuthCustomToken.cs AuthCustomToken.swift
retries: A 429 with Retry-After, retried retries.rs retries.ts retries retries.py Retries.java Retries.cs Retries.swift
concurrent-calls: Several calls at once on one client concurrent-calls.rs concurrent-calls.ts concurrent-calls concurrent_calls.py ConcurrentCalls.java ConcurrentCalls.cs ConcurrentCalls.swift
config-load: A client from load, with where each setting came from config-load.rs config-load.ts config-load config_load.py ConfigLoad.java ConfigLoad.cs ConfigLoad.swift
login-device: A person signs in with the device flow and calls as that person (Rust, the login feature) login-device.rs none none none none none none

Swift builds only on a Mac, so the release workflow runs all of it on a macOS runner and attests the commit itself (examples-attest in release.yml, docs/releasing.md). By hand, a Mac run (python3 tools/run-examples.py --lang swift) writes its own results file for the same commit as a Linux run, and the attest step takes both: mise run examples:attest -- --results linux.json --results mac.json (both must be for the same clean commit, and every language needs a passing example). The Python run uses uv run --frozen, so examples/python/uv.lock is not rewritten (uv bumps the inorbithr version in it otherwise, and a dirty tree fails the gate). If you run uv run by hand, revert the lock before attesting.

Not shown yet:

  • swift / stream-socket: the Swift SDK has no WebSocket stream transport yet
  • every language but Rust / login-device: the login feature is Rust-only until the other SDKs ship theirs (RFC 0231). The check drives the device flow against the replay server, because the check path runs programs with environment variables and no browser; the browser flow is covered by the conformance cases

Earlier examples

These predate the table above and stay. Some show the same thing as a call type (whoami is unary-get, load is config-load, events is stream-sse, custom_token is auth-custom-token); they are compiled by examples:check but not replayed.

Shows Rust TypeScript Go Python Java C# Swift
Who the API thinks you are (GET /v1/me), with the credentials in the environment whoami.rs whoami.ts whoami whoami.py, whoami_async.py Whoami.java Whoami Whoami
A client built with load, where each setting came from, a middleware of your own load.rs, middleware.rs load.ts load configured.py Configured.java Load
The account's events as they happen (events:read), over server-sent events or the /v1/ws socket stream_events.rs events.ts events stream_events.py
A token provider of your own, and matching on error codes custom_token.rs
Every item of a paged list, then one page of another ListMonitors

Running one needs an API token or key: create one in the console (API tokens and keys) or with iohr token create, or sign in with iohr login for the load examples. Examples never print the secret or the token.