clj-grpc.server — com.github.bpalermo/clj-grpc 0.1.2

A gRPC server over non-shaded Netty, from a service value and plain functions.

(-> (server {:services [{:service greeter/Greeter
                         :handlers {:say-hello (fn [req] ...)}}]
             :port 8080})
    start)

Handler shapes, by method type — requests and responses are protobuf Messages; compose with the generated proto->X / X->proto at the edges:

:unary (fn [request] response) :server-streaming (fn [request send!]) — call send! per message, return to complete :client-streaming (fn [respond!]) -> {:on-next (fn [msg]) ... :on-complete (fn [])} — call respond! once with the response, usually from :on-complete :bidi (fn [send! close!]) -> {:on-next ... :on-complete ...} — send! per message, close! to finish

A thrown exception in any handler becomes Status/INTERNAL with the message attached; throw an io.grpc.StatusRuntimeException to control the status.

opts: :services [{:service Service :handlers {kebab-key fn}} ...] :address SocketAddress | port | {:unix path} | "unix:///path" :port used when :address is absent; default $PORT, else 8080 — the Knative convention :transport :auto (default) | :epoll | :nio — UDS requires epoll :health true (default) — grpc health service, wired for probes :reflection false (default) — server reflection (v1) :executor java.util.concurrent.Executor for handlers, or :direct to run them ON the Netty event loop — measured ~29% off unary latency, and a sharp edge: a handler that blocks on a direct executor stalls the transport for every connection sharing that loop. Opt in only for handlers that provably never block. :interceptors [io.grpc.ServerInterceptor ...] :permit-keepalive {:time-ms n :without-calls bool} — the pings this server ACCEPTS. gRPC's default permit is 5 minutes and calls-only; a client pinging faster gets GOAWAY too_many_pings, so a server whose clients keep connections warm (Knative, LBs) must lower this to match. clj-grpc.knative pairs the two. :max-inbound-message-size bytes :tls {:cert-chain File/path :private-key File/path}; absent means h2c (plaintext HTTP/2), which is what Knative speaks

Handlers run on virtual threads by default (:executor overrides): Clojure handlers block — that is the model — and grpc's default shared pool is sized for handlers that never do.

await-termination clj

(await-termination {:keys [server]})

port clj

(port {:keys [server]})

server clj

(server {:keys [services address port transport health reflection executor
                interceptors tls permit-keepalive max-inbound-message-size]
         :or {health true}})

Build (without starting) a server. Returns {:server io.grpc.Server :health HealthStatusManager-or-nil :address SocketAddress}.

service-definition clj

(service-definition {:keys [service handlers]})

A dynamic ServerServiceDefinition from a service value and a handlers map. Methods without a handler are omitted and answer UNIMPLEMENTED, which is gRPC's own semantics for them.

shutdown clj

(shutdown s)

(shutdown {:keys [server health owned-executor] :as s} {:keys [grace-ms]})

Graceful by default; :grace-ms bounds the drain, then forces. The health service (when present) enters its terminal NOT_SERVING state first, so load balancers stop routing before the listener closes — the drain order Kubernetes rollouts assume.

start clj

(start {:keys [server] :as s})