استدعاءات RPC أحادية الاتجاه ومن الخادم ومن العميل وثنائية الاتجاه

gRPC defines four kinds of method in your .proto file, and each one maps to a different streaming shape:

• Unary — one request, one response (like a normal function call).
• Server streaming — one request, a stream of responses.
• Client streaming — a stream of requests, one response.
• Bidirectional streaming — both sides stream independently.

The stream keyword in the service definition is what decides the shape. In this lesson you'll implement all four in Node.js with @grpc/grpc-js and learn when to reach for each.

Before you implement any handler, you load the .proto definition at runtime with @grpc/proto-loader and turn it into a gRPC service object with @grpc/grpc-js.

The loaded packageDefinition mirrors your proto packages and services. You attach handlers to the service with server.addService() — the names you provide must match the rpc names exactly.

A unary handler receives (call, callback). The request payload is on call.request, and you reply by invoking the Node-style callback(error, response).

• Pass null as the first argument for success.
• Pass a { code, details } error object to signal failure.

Unary is the right choice for classic request/response work: fetching a record, validating input, performing a single mutation.

A server-streaming handler receives only (call) — there is no callback. You push each response with call.write(message), then signal completion with call.end().

This pattern shines when the server produces a sequence the client can consume incrementally: paginated results, log tails, progress events, or large result sets you don't want to buffer in memory.

call.write() returns a boolean. When it returns false, the internal buffer is full and you should wait for the 'drain' event before writing more. Ignoring this on large streams can balloon memory usage.

The robust pattern wraps writes in a promise that resolves on drain, so an async loop naturally pauses when the consumer is slow.

A client-streaming handler receives (call, callback). You listen for incoming items with call.on('data', ...), do final work on call.on('end', ...), and send the single response via the callback.

Use it when the client feeds many items but you only need one aggregate result: bulk uploads, batched metrics ingestion, or computing a summary/average over a stream.

A bidirectional handler receives only (call) and treats it as a duplex stream: read incoming items with call.on('data', ...) and emit responses with call.write(...) at any time. Both directions are fully independent.

This is ideal for chat, multiplayer state sync, or live request/response negotiation where either side may speak first or out of lockstep.

The client API mirrors the server shapes. Unary returns via a callback; server streaming returns a readable stream you iterate with 'data'; client streaming gives you a writable stream you write() to and then end(); bidirectional gives you both at once.

The single rule: the stream keyword on each side of the proto determines whether you get a callback or a stream object.

Choosing the right RPC type is almost always a question of cardinality on each side:

• One request, one response → unary.
• One request, results arrive over time → server streaming.
• Many inputs collapsed into one result → client streaming.
• Continuous, independent two-way flow → bidirectional.

Don't reach for streaming just because data is large — pagination over unary calls is often simpler. Reach for streaming when the data is open-ended in time or genuinely incremental.

Here's a tiny, framework-free helper that encodes the decision rule above. It takes whether each side streams and returns the gRPC method type — useful as a sanity check when designing a service.

This is plain JavaScript with no gRPC dependency, so an online judge can run it directly.

Across all four types, a few production habits matter:

• Always attach call.on('error', ...) on streaming handlers — an unhandled stream error can crash the process.
• Respect deadlines: check call.cancelled in long loops and stop writing if the client gave up.
• For client/bidi streams, do final work in 'end', not after the first 'data'.
• Send domain errors with grpc.status codes (e.g. NOT_FOUND, INVALID_ARGUMENT) rather than throwing raw exceptions.

Test your understanding of choosing the right RPC type.

You now know all four gRPC call shapes and how to implement them in Node.js with @grpc/grpc-js:

• Unary — (call, callback); read call.request, reply once.
• Server streaming — (call); call.write() repeatedly, then call.end(), minding backpressure via 'drain'.
• Client streaming — (call, callback); aggregate on 'data', respond once on 'end'.
• Bidirectional — (call); read and write independently for live, two-way flows.

Choose by cardinality and whether the data is open-ended in time, always handle stream errors, and respect client deadlines with call.cancelled.