Guides / Java / API reference

Java API reference

Every public type of com.kosa8:kosa8 0.1.2, package com.kosa8. Signatures are copied from the source, and the list of members on this page was checked against javap -public run on the jar from Maven Central. Paths are the daemon's native API; … stands for /kosa8/v1/sandboxes/{sandbox}.

What this is, in plain words

This page is the dictionary: every class and method the Java SDK offers, with exactly what it takes, what it gives back and how it can fail. If you are new to kosa8, start with the quickstart; come here when you need the precise detail of one call.

Conventions

• Artifact. com.kosa8:kosa8:0.1.2 on Maven Central. Class files for Java 17 (major version 61); no dependencies. The jar has no module-info and no Automatic-Module-Name, so on the module path it is the automatic module kosa8.
• Exceptions are unchecked. Every method may throw a subclass of Kosa8Exception (a RuntimeException). The column "throws" below lists only what is specific to a method; any call to the daemon can also throw ConnectionException, TimeoutException and an ApiException for an HTTP error.
• JSON values. Methods with no result record return the daemon's JSON decoded by Json: objects as Map<String, Object> (insertion-ordered), arrays as List<Object>, whole numbers as Long, other numbers as Double. An empty answer decodes to null, which methods returning a map turn into an empty map.
• Options may be null. Every Options.* argument accepts null, meaning "none". Sandbox, container and snapshot ids may not be null. Ids are URL-encoded into the path.
• Approvals. Every option class extends Options.Call and carries an optional signed approval, sent as the X-Kosa8-Approval header (trimmed; not sent when blank). Methods whose only option is an approval take Options.Approval.
• Transport. One connection per request, HTTP/1.1 with Connection: close, Accept: application/json and X-Kosa8-Actor on every request. No User-Agent is sent.
• Threads. Kosa8Client and Sandbox are immutable and safe to share. Option builders are not. See Thread safety for the two checkpoint caveats.

Kosa8Client

public final class Kosa8Client {
  public static final String VERSION = "0.1.2";
  public static Builder builder();
  public Endpoint endpoint();
  public Sandbox sandbox(String id);
  // … the methods in the tables below
}

There is no public constructor; use builder(). endpoint() reports where requests go. sandbox(id) returns a Sandbox handle and sends nothing. VERSION is the SDK's own version. The class does not implement AutoCloseable: it holds no connection.

Kosa8Client.Builder

public static final class Builder {
  public Builder();
  public Builder socketPath(String v);
  public Builder host(String v);
  public Builder token(String v);
  public Builder insecure(boolean v);
  public Builder actor(String v);
  public Builder agentToken(String v);
  public Builder headers(Map<String, String> v);
  public Builder timeout(Duration v);
  public Builder checkpoints(CheckpointStore v);
  public Builder getenv(Function<String, String> v);
  public Kosa8Client build();
}

Daemon

Sandboxes

Running code

How run, exec and attach collect. Frames with stream stderr go to stderrBytes and onStderr; status frames go only to onStatus; any other stream, or none, goes to stdoutBytes and onStdout. Frames with no data are skipped. The first done frame ends collection: with error set it throws StreamException (with the output so far), otherwise it yields Exec(exit, stdout, stderr), with exit 0 if the frame had none. A stream that ends with no done frame throws StreamException("stream ended unexpectedly (no final frame)"); a broken stream throws StreamException("stream broke: …") with the output so far; a time limit throws TimeoutException, without output. A non-zero exit is not an exception. The daemon also reports an unpulled image or an unknown container this way (seen).

Snapshots, fork and explore

Checkpoints

Sandbox

A handle bound to one sandbox id, from client.sandbox(id). No public constructor. Every method delegates to the client method in the right-hand column with the handle's id. An approval travels in the options object where a method takes one; start, stop, pull, startContainer, checkpoint and rewind take none, so use the client's overloads for gated calls of those.

Not on the handle: restoreSnapshot, deleteSnapshot, and the client overloads that take an Options.Approval for start, stop, pull, startContainer, checkpoint and rewind. (0.1.0's handle also lacked execFrames, startInteractive, writeStdin and attach.)

Options

A holder class (no instances) for the per-call option builders. Each is a public class with a public no-argument constructor; every setter returns this. Fields are package-private, so you cannot read back what you set. Unset fields are not sent.

Options.Call<T> and Options.Approval

public static class Call<T extends Call<T>> {
  public T approval(String a);          // X-Kosa8-Approval
}
public static final class Approval extends Call<Approval> {
  public static Approval of(String sig);
}

Every option class below extends Call, so all of them have approval(…).

Options.Create

Options.Delete

Options.Run

For run, exec and attach.

Options.Interactive

Options.Snapshot, Options.Restore, Options.SnapshotDelete, Options.Fork

Options.Explore

Results

A holder class for the result records. Records are immutable, but Exec's byte arrays are returned as is, and record equality compares arrays by reference, so two Execs with the same output are not equals.

public record Exec(int exitCode, byte[] stdoutBytes, byte[] stderrBytes) {
  public String stdout();    // UTF-8
  public String stderr();    // UTF-8
  public boolean ok();       // exitCode == 0
}
public record Fork(List<Map<String, Object>> forks, Object snapshot, long forkMs, int count) {}
public record ExploreBranch(String name, String variant, int exit, String output, String error, long durationMs) {}
public record Explore(String parent, List<ExploreBranch> branches, String winner, int removed) {}
public record CheckpointSaved(Checkpoint checkpoint, List<String> evicted, Map<String, Object> snapshot) {}
public record Rewind(Object sandbox, Checkpoint checkpoint, List<String> dropped, Object restoreMs) {}

Checkpoint

public record Checkpoint(String id, String sandbox, String label, boolean auto, Instant created) {}

id is <sandbox>-ckpt-<n>. label is never null ("" when none). auto is false for every checkpoint the SDK takes. created is Instant.EPOCH if the stored timestamp cannot be parsed.

Checkpoint stores

public interface CheckpointStore {
  Map<String, List<Checkpoint>> load();                                   // a copy of the stacks
  <T> T update(Function<Map<String, List<Checkpoint>>, T> fn);          // run fn on a mutable copy, save, serialised
}

public final class FileCheckpointStore implements CheckpointStore {
  public FileCheckpointStore();                 // ~/.kosa8/checkpoints.json (from user.home)
  public FileCheckpointStore(Path path);                          // lock timeout 10 s
  public FileCheckpointStore(Path path, Duration lockTimeout);    // 0.1.1
  public Path path();
  public Map<String, List<Checkpoint>> load();
  public <T> T update(Function<Map<String, List<Checkpoint>>, T> fn);
}

public final class MemoryCheckpointStore implements CheckpointStore {
  public MemoryCheckpointStore();
  public synchronized Map<String, List<Checkpoint>> load();
  public synchronized <T> T update(Function<Map<String, List<Checkpoint>>, T> fn);
}

A custom store must return copies from load (the SDK does not modify them) and make update atomic with respect to other updates. If fn throws, the store should not save; both built-in stores propagate the exception without writing.

Lower-level pieces

Endpoint

public record Endpoint(String socketPath, String scheme, String host, int port, String basePath, String token) {
  public boolean isUnix();                     // socketPath != null
  public String target();                      // "unix://" + socketPath, or scheme://host:port (no token)
  public static String defaultSocketPath();    // $user.home/.kosa8/run/kosa8.sock
  public static Endpoint resolve(String host, String socketPath, String token, boolean insecure,
                                 Function<String, String> getenv);
}

resolve applies the CLI's KOSA8_HOST rules (what build() calls):

1. No host and an empty KOSA8_HOST: the unix socket socketPath, or the default.
2. The value is trimmed and trailing slashes removed; the scheme is lower-cased.
3. unix:///path: that socket. tcp:// is treated as http://. No scheme: http://. Any other scheme: Kosa8Exception.
4. No host in the URL: Kosa8Exception("KOSA8_HOST \"…\" names no host"). Default port 443 for https, 80 for http.
5. Plain http to a host other than localhost, ::1 or 127.*, without insecure or KOSA8_INSECURE=1: Kosa8Exception.
6. token: the argument, else KOSA8_TOKEN only when the host came from the environment; an empty token is null.
7. basePath: the URL's path without trailing slashes, prefixed to every request.

getenv null means System::getenv. toString() is overridden and never prints the token 0.1.1: it gives Endpoint[unix:///path] or Endpoint[scheme://host:port/base, token=***] (seen: Endpoint[https://worker.example.com:443/k8, token=***]). token() still returns it.

Frame

public record Frame(String stream, byte[] data, boolean done, boolean ok, String error, Integer exit, String id) {}

One NDJSON line of a run, exec or attach stream. data is base64-decoded (empty array when absent); empty strings in stream, error and id become null; exit is null except on a final frame that carries one. On the final frame (done true), ok says the stream ended cleanly, not that the command succeeded (seen: ok=true exit=4). Frames reach you only through execFrames.

Json

public final class Json {
  public static Object parse(String s);     // throws IllegalArgumentException("bad JSON: …") on bad input
  public static String write(Object v);
}

parse: objects to LinkedHashMap<String, Object>, arrays to ArrayList<Object>, integers to Long (to Double if too big for a long), numbers with a fraction or exponent to Double, plus String, Boolean and null. Trailing data is an error. write: Map (keys via String.valueOf), Iterable, Object[], String, Boolean, Integer/Long/Short as is, other Numbers through double (whole values under 10¹⁵ without a fraction), null; anything else as the JSON string of its toString(). Non-ASCII is written as is (UTF-8).

Kosa8Exception

public class Kosa8Exception extends RuntimeException {
  public Kosa8Exception(String message);
  public Kosa8Exception(String message, Throwable cause);
  public Kosa8Exception(String message, int status, String daemonMessage, String remediation,
                        String method, String path, Object body, Throwable cause);
  public int status();              // HTTP status, or 0
  public String daemonMessage();    // the daemon's "error" text, verbatim
  public String remediation();      // the daemon's "remediation"
  public String method();
  public String path();
  public Object body();             // decoded response body
}

For an HTTP error the message is the body's error (or message), with (remediation) appended when the body has one; a non-JSON body is used as the message, trimmed; an empty one gives "request failed with HTTP <status>". Real messages and handling advice are on Java errors and troubleshooting.