SDKs

Install and import

A copied TypeScript file is imported as ./index.ts, and a copied Ruby file as require_relative "kloudlite".

The distribution of the Python package is kode-sdk, and its import name is kode. The command pip install kloudlite installs a different package, the client of the model and dataset hub.

Secret references

An environment value refers to a secret of the owner as ${{ secrets.NAME }}. With the team as the owner, the secrets calls work on your own secrets in that team; give the scope team for the secrets of the team. The secrets API lists the routes that take a reference.

Pipeline definitions

The definition of pipelines.create and pipelines.update is plain data in the shape of Pipeline definition. Python takes a dict, Ruby a hash, and TypeScript an object. Go takes PipelineDefinition, which is raw JSON bytes, and Java takes a JSON string.

The order of jobs, inputs, and each matrix is part of the definition. Python, Ruby, and TypeScript keep the order that you write. Go and Java send the bytes that you give, so write the keys in the order that you want.

A save returns the pipeline with its version. rotate_webhook returns the new URL, which no later call shows.

Authentication and base URL

The SDK uses the login of kode, so a client needs no arguments. It takes the API origin and the token from the first source that has each, adds /v1 to the origin, and sends the token as Authorization: Bearer.

config.json is in KODE_CONFIG_DIR, or in ~/.config/kode. For a CI job or a server with no kode, set KODE_URL and KODE_TOKEN. The token is a CLI login or an API token. An API token opens only the routes within its reach and grants. A pipeline run or a capsule that it starts is recorded under the name of the token.

With no token, the SDK stops with no Kode login: pass token=, set KODE_TOKEN, or run kode login. With a token and no origin, the sentence is no Kode API URL: …. The error type differs by language:

• Python: RuntimeError, raised by Kloudlite().
• TypeScript: Error, thrown by new Kloudlite().
• Go: kloudlite.New returns no error. The first call returns it, and Client.Err() returns it at once.
• Ruby: RuntimeError, raised by Kloudlite::Client.new.
• Java: IllegalStateException, thrown by new Kloudlite().

Every request times out after 30 seconds. Set the limit with timeout (Python, Ruby), timeoutMs (TypeScript), or Options.Timeout (Go). Java has no setting for it.

Inputs, results, and errors

Every input is named. Python takes keyword-only arguments, Ruby keywords, TypeScript one options object, Go one request struct (kloudlite.CreateWorkspace{Workspace: …}), and Java a nested params class (new Kloudlite.CreateWorkspace().workspace(…)).

A workspace, environment, or desk is "name" for your own or "team/name" for a team's, or its id. Something new made from an existing one is to.

Every method returns the decoded JSON of the route, except the capsule and pipeline handles below. Java returns the raw JSON string from every method, except those two.

Errors, one per SDK:

• Python: ApiError with status and message; CapsuleTerminated, a subclass, when a capsule that you wait for has ended.
• TypeScript: ApiError with status and message; TimeoutError when a client-side wait runs out. A terminated capsule is an ApiError with status 409.
• Go: *ApiError with Status and Message; ErrTimeout, tested with errors.Is, when a wait runs out. A terminated capsule is an *ApiError with status 409.
• Ruby: Kode::ApiError with status and message; CapsuleTerminated < ApiError; TimeoutError when a wait runs out.
• Java: Kode.ApiException, an IOException, with public status and message.

A missing required field is refused before anything is sent: ValueError in Python, an IllegalArgumentException in Java.

Methods

Resources hang off the client under these names: workspaces, environments, desks, volumes, secrets, connectors, capsules, and pipelines. Java reaches them as a call, kl.workspaces() and Go as the field kl.Workspaces. The ide, capsule, process, and run rows are on objects that those methods return. workspaces.ide returns the tool-server client. capsules.create, get, and list return capsule handles. pipelines.run and get_run return a run handle.

Python also has an .aio form of its calls for asyncio. Every cell is the method name in that language.

The tool-server rows call the tool server directly with the workspace's token, so they take the tool's own arguments. The SDKs have no method for these resources: teams, invites, keys, tokens, container images, requests, and regions.

Two tool-server tools have no typed method, process_close_stdin and process_wait; call reaches them in every language.

The capsule attach is a WebSocket and is not in the SDKs. attach raises an error in every language, so use kode capsules attach. The SDKs have no capsule exec, read, or write, and no process classes. capsules.run answers exit_code, stdout (stdout and stderr together), an empty stderr, and capsule.