clj-grpc.client — com.github.bpalermo/clj-grpc 0.1.14

Channels and calls, from the same methods map the server consumes.

(def ch (channel "localhost:8080" {:plaintext true}))
(invoke ch (:say-hello greeter/greeter-methods) request)

Call shapes, by method type: :unary request -> response (blocking) :server-streaming request -> lazy seq of responses (blocking iterator) :client-streaming -> {:send! (fn [msg]) :close! (fn []) :response promise :ready? :request! :error!} :bidi observer-map -> {:send! ... :close! ... :ready? ...}; responses arrive through the caller's {:on-next ...} map

Flow control on the streaming-out shapes, the client mirror of the server's. send! returns whether the transport wants more: false means grpc-java is now buffering this call's messages because the peer is not reading them fast enough, and .onNext neither blocks nor refuses, so a producer faster than its consumer grows that buffer without bound. :ready? asks the same question without sending.

THE FIRST ANSWER IS OFTEN FALSE AND DOES NOT MEAN BACKPRESSURE: a call's stream is not up at the moment invoke returns, and readiness is false until it is. A producer that reads that first false as a signal to stop stalls on its own first message. Wait for :on-ready, or simply send — a reply per request cannot outrun anything, and .onNext never refuses.

To wait rather than poll, pass :on-ready in the observer map (:bidi) or in opts (:client-streaming); grpc calls it when a full call has drained. THE SAME RULE AS THE SERVER APPLIES: grpc serializes a call's callbacks, so the thread running one must never wait for another. A producer that wants to wait needs its own thread, parked on something :on-ready delivers to.

Inbound credits, for a :bidi caller that wants to pace what it receives: :inbound-credits n in the observer map stops grpc requesting messages automatically and asks for n, after which :request! asks for more. Without it responses arrive as fast as the server sends them.

channel clj

(channel target
         {:keys [plaintext transport keepalive idle-timeout-ms
                 max-inbound-message-size interceptors default-service-config
                 executor]})

target: "host:port" | "dns:///..." | "unix:///path" | {:unix path} opts: :plaintext true for h2c — what a Knative service speaks; default true for unix targets, false otherwise :transport :auto (default) | :epoll | :nio; UDS requires epoll :keepalive {:time-ms n :timeout-ms n :without-calls bool} — keep the connection warm through idle proxies (Knative activator) :idle-timeout-ms channel idle timeout :max-inbound-message-size bytes :interceptors [f-or-ClientInterceptor ...] — fns of the call, (fn [call next] ...), mixed with raw ClientInterceptors; [a b c] runs a outermost. See clj-grpc.interceptor. invoke's opts take the same key per call. :executor Executor for callbacks, or :direct (same sharp edge as the server, sharper: every channel in the process shares one event loop group per transport, so a direct callback that blocks stalls other channels' I/O too) :default-service-config map, e.g. retry policy (enables retries when set)

client clj

(client ch methods)

(client ch methods default-opts)

The whole service as a map of fns: {:say-hello (fn [request] ...), ...}.

invoke clj

(invoke ch method request)

(invoke ch
        {:keys [type method-descriptor]}
        request
        {:keys [interceptors headers] :as opts})

Call one method. The blocking shapes block; the streaming-in shapes return immediately with the request-side controls.

opts: :deadline-ms, :wait-for-ready, and per call :headers a map of outgoing headers for this call :interceptors [f-or-ClientInterceptor ...] for this call, outermost relative to the channel's; see clj-grpc.interceptor :on-ready :client-streaming only — the :bidi shape takes it in the observer map, next to :on-next

The streaming-in shapes return {:send! :close! :error! :ready? :request!}, where send! answers whether the transport wants more; see this namespace's docstring for the whole flow-control contract.

shutdown clj

(shutdown ch)

(shutdown ch {:keys [grace-ms]})

Graceful by default; :grace-ms bounds the drain, then forces.

Nothing to release beyond the channel: channels share one event loop group per transport for the life of the process, so shutting one down frees no threads and opening the next allocates none. See clj-grpc.impl.netty/shared-channel-groups for why that is the ownership split, and clj-grpc.server/shutdown for the half that does release loops.