Struct APIBuilder 

pub struct APIBuilder { /* private fields */ }

An API server whose routes can be added and removed at runtime.

APIBuilder serves HTTP and gRPC on a given address, on a single port. gRPC is HTTP/2 with a distinct route naming convention, so both protocols share one router and one server. Route additions and removals are handled by subscribing to assertions/retractions of DynamicRoute in the DataspaceRegistry.

Adding and removing routes

Any process that wants to dynamically register API routes can simply assert a DynamicRoute in the DataspaceRegistry. Retracting the assertion will remove the route, either when retracted manually or when the process owning the route assertions exits.

If the API server is restarted, it will re-register any routes that were previously asserted.

Static handlers and services

In addition to dynamic routes, callers can register static HTTP handlers and gRPC services up-front via with_handler, with_optional_handler, and with_grpc_service. These form a base router that’s cloned on every rebuild and merged with the currently asserted dynamic routes. Static routes take precedence on conflicts: a dynamic route whose path and method overlap with a static route is skipped (with a warning) until the conflict clears.

HTTP and gRPC routes share one path space, so a gRPC route can, in principle, collide with an HTTP one. In practice, this should never occur because the structure of gRPC routes includes programmatic aspects (/<package>.<service>/<method>) that don’t collide with any typical HTTP routes registered by components.

Assertions

See HttpServer for more information on available assertions. The server ID provided by APIBuilder to the underlying HttpServer will be privileged-api or unprivileged-api, depending on the configured endpoint type.

Supervision

The API can’t be run directly: into_supervisor turns it into the Supervisor that runs it, which is then added to another supervisor like any other child.

Implementations

impl APIBuilder

pub fn new(endpoint_type: EndpointType, listen_address: ListenAddress) -> Self

Creates a new APIBuilder for the given endpoint type and listen address.

pub fn with_handler<H>(self, handler: H) -> Self

where H: APIHandler,

Adds the given handler as a static HTTP handler.

The handler’s initial state and routes are merged into the base router. These routes are always served by the API regardless of which dynamic routes are currently asserted.

pub fn with_optional_handler<H>(self, handler: Option<H>) -> Self

where H: APIHandler,

Adds the given optional handler as a static HTTP handler.

If handler is Some, its initial state and routes are merged into the base router. Otherwise the builder is returned unchanged.

pub fn with_grpc_service<S>(self, svc: S) -> Self

where S: Service<Request<GrpcBody>, Response = Response<GrpcBody>, Error = Infallible> + NamedService + Clone + Send + Sync + 'static, S::Future: Send + 'static, S::Error: Into<Box<dyn Error + Send + Sync>> + Send,

Adds the given gRPC service as a static service on the base router.

pub fn with_tls_config(self, config: ServerConfig) -> Self

Sets the TLS configuration for the server.

pub fn with_self_signed_tls(self) -> Self

Sets the TLS configuration for the server based on a dynamically generated, self-signed certificate.

pub fn try_with_self_signed_tls(self) -> Result<Self, GenericError>

Sets the TLS configuration for the server based on a dynamically generated, self-signed certificate.

Errors

If the certificate cannot be generated, the TLS configuration cannot be built, or the resulting TLS configuration is not FIPS compliant, an error is returned.

impl APIBuilder

pub fn into_supervisor(self) -> Supervisor

Converts this builder into a supervisor.

The supervisor is configured to run the underlying HTTP/gRPC server, as well as a worker to manage the dynamic route updates as routes are asserted and retracted.