Crate solti_api 

solti-api

Public task transports for a Solti agent.

HTTP uses the model-owned CRD JSON representation. gRPC uses versioned protobuf messages. Both transports delegate domain operations to one ApiHandler.

This crate does not store or execute tasks.

Start Here

Use ApiHandler to define the transport-independent backend. Use SupervisorApiAdapter to connect that boundary to solti-core. Use HttpApi to build a standalone axum router or mount documented routes into an application router. Use GrpcApi to build a tonic service.

Flow

HTTP CRD JSON ── parse and validate ──┐
                                      ▼
                                 ApiHandler
                                      ▲
gRPC v1 DTO ── convert and validate ──┘
                                      └──► custom backend or solti-core

The transports own wire validation, authentication, metrics, and error mapping. The handler owns task operations.

Desired State

The bundled adapter commits desired state before reconciliation finishes. A successful create or apply does not mean that execution has started. Clients observe reconciliation through status.conditions[type=Reconciled].

Apply is an upsert without write preconditions. Apply and delete can check uid and resourceVersion.

Collections and Streams

Lists use opaque continuation tokens. The bundled adapter provides snapshot-consistent pagination. Watches can resume from a retained resource version.

Task output is live-only and lossy. It is not persisted or replayed. A slow subscriber receives a Lagged event.

Workload Boundary

The built-in Embedded workload is available only through the in-process SDK. HTTP and gRPC reject it. Extension workloads remain visible.

Feature Flags

Feature	Capability
core-adapter	SupervisorApiAdapter for solti-core
grpc	tonic gRPC service and generated current client
grpc-tls	solti-tls adapter for tonic; implies grpc
http	axum HTTP/JSON router

No feature is enabled by default.

Main Types

Area	Types
Handler	ApiHandler, ApiError
Streams	TaskWatchEventStream, OutputEventStream
Metrics	ApiMetricsBackend, ApiMetricsHandle, Transport
HTTP	HttpApi, HttpApiParts
gRPC	GrpcApi, grpc::wire
Core adapter	SupervisorApiAdapter

Quick Start

Build both transports from one handler:

let handler = Arc::new(SupervisorApiAdapter::new(supervisor));
let grpc = GrpcApi::new(handler.clone()).server();
let http = HttpApi::new(handler).build();

Re-exports

pub use grpc::GrpcApi;

pub use tonic;

pub use axum;

pub use aide;

Modules

grpc

gRPC Transport

Structs

ApiConflict

Structured optimistic concurrency conflict.

ApiErrorCause

One machine-readable cause of an API conflict.

HttpApi

Builder for the axum task API.

HttpApiParts

Standalone runtime router and its generated OpenAPI contract.

NoOpApiMetrics

Metrics backend that ignores every update.

SupervisorApiAdapter

ApiHandler implementation backed by SupervisorApi.

Enums

ApiError

Error returned by the handler or a transport boundary.

Transport

Transport that served an API request.

Constants

API_VERSION

Current public API major version.

API_VERSION_NAME

Current public API version name.

GRPC_API_PACKAGE

Current gRPC package exposed by the agent.

GRPC_API_SERVICE

Current gRPC service exposed by the agent.

HTTP_API_ROOT

Root path of the HTTP Kubernetes API group.

MAX_REQUEST_BYTES

Maximum HTTP request body and gRPC message size.

Traits

ApiHandler

Transport-independent task API.

ApiMetricsBackend

Receives API request lifecycle metrics.

Functions

noop_api_metrics

Creates a shared no-op metrics backend.

to_tonic_server_tls

Converts Solti server TLS settings into tonic settings.

Type Aliases

ApiMetricsHandle

Shared metrics backend handle.

OutputEventStream

Boxed live stream of task output events.

TaskWatchEventStream

Boxed stream of task resource changes.