Docs
Kiwi Distro
Version Current

Concept

Architecture overview

The middleware, workers and clients, the pull-based delivery model, and how clusters and TLS fit together.

Distro Current 3 min read Updated

Note

Kiwi Distro is currently in private preview. Interfaces and behaviour described here can change before general availability. Contact Kiwify Labs for access.

Components#

text
  client --(HTTPS, OAuth2)--> [ middleware ] <--(HTTPS, OAuth2)-- worker (one service)
  client --(HTTPS, OAuth2)--> [ middleware ] <--(HTTPS, OAuth2)-- SideCar (worker for a REST API)
                                  |
                       transaction cache, message broker, data and secrets stores
  • The middleware authenticates callers, applies authorisation, queues requests, selects a worker, correlates the response and stores feedback.
  • A worker registers for one service, pulls its queued requests, runs the handler and posts the result.
  • A client invokes methods and administers the middleware.
  • The SideCar is a worker that proxies REST APIs. Scripts run on workers that advertise the right executor.

Services only know the names of the services they call, never where those run.

Request lifecycle#

  1. The client authenticates (/client/auth_token) and posts a method request.
  2. The middleware authorises the call, finds capable workers and queues the request for the chosen worker.
  3. It signals the worker that work exists. The signal is only a hint; work is always pulled.
  4. The worker drains its queue with a single read, locks the request if required (so two workers do not both process it), runs the handler, optionally sending progress feedback, and posts the response.
  5. The middleware returns the envelope to the waiting client, or stores it for a later pick-up or a callback.

Delivery modes#

Mode "There is work" signal Notes
Eager (default) The worker's own long-poll GET /worker/messages?wait=N returns when work is queued No inbound port is needed. Works behind any load balancer whose idle timeout exceeds the wait
Lazy A TCP pull_signal sent to the worker's wake-up probe port The middleware must be able to reach the worker's ip:port. Fully load-balancer agnostic
Connected A SignalR pull_signal Needs session affinity and WebSocket support on the hub path. Currently for .NET workers

No mode runs a periodic backstop poll.

State and clustering#

A standalone middleware stores its data in an embedded database (LiteDB). In cluster mode, several middleware instances run behind a load balancer and share state:

Category Backend
Transaction cache and message broker (peer pub/sub) Redis
Data, secrets and feedback MongoDB

Storage backends are pluggable modules, selected by configuration. A required capability that a chosen backend does not provide (for example a cache adapter) is detected at start-up and fails fast, rather than misbehaving at request time. Configuration can be centralised in Kiwi Vault, which also acts as the cluster's certificate authority.

TLS#

Each middleware instance serves HTTPS with a certificate issued, and automatically renewed, by the Kiwi Vault PKI from one root CA. Workers and clients pin that CA on first use. See TLS and CA trust.

Feedback#

Handlers can emit structured progress while they run. It is persisted and queryable by worker, request, service, type and tags (kiwi distro list-feedback).