{"canonical_url":"https://engineer.company/glossary/grpc/","content_markdown":"# gRPC\n\n## What it is\n\ngRPC is a framework for remote procedure calls. A program calls a method on a\nserver that runs on another machine as though the server were a local object,\nand gRPC carries the call across the network in a protocol of its own, on top of\nHTTP/2, and brings the answer back as a return value.\n\nEverything starts with a service definition: a list of remote operations and the\nrequest and response types each one accepts. By default it is written in\nProtocol Buffers, Google's open source format for serialising data independently\nof language and platform, in a file whose name ends in `.proto`. Other formats\ncan be plugged in, but protocol buffers are what gRPC uses unless told\notherwise. The compiler `protoc`, together with a gRPC plugin, reads the file\nand generates code for both halves. The client gets a stub, a local object with\nthe same methods as the service (some languages simply call it the client), and\nthe server gets an interface to implement. Since both halves come from one file,\na server written in Java can answer clients written in Go, Python or Ruby.\n\nA method has one of four shapes. A unary method takes one request and returns\none response, like an ordinary function call. A server streaming method takes\none request and sends back a stream of responses, a client streaming method does\nthe reverse, and a bidirectional streaming method lets both sides send their\nstreams independently. Within a single call, gRPC guarantees that messages\narrive in the order they were sent.\n\nOn the wire, gRPC runs over HTTP/2. Every call is a `POST` to a path made of the\nfully qualified service name and the method name, with the content type\n`application/grpc`. Each message travels behind a five-byte prefix: one byte\nthat says whether the message is compressed, and four that give its length. The\noutcome of the call is not the HTTP status. A response that gRPC produces\ncarries status 200 even when the call fails, and the real result comes in\ntrailers, header fields sent after the body: `grpc-status` with a number and,\noptionally, `grpc-message` with a description of the error.\n\nThat makes it a different animal from REST. A REST API names resources and acts\non them with HTTP's own methods and status codes, usually with JSON bodies that\nanyone can read. A gRPC API is a list of methods with typed, binary messages,\nand HTTP/2 is only the transport underneath. The Protocol Buffers documentation\ncompares the format with JSON while emphasising its smaller messages and faster\nprocessing.\n\n## Why it matters\n\nThe contract comes first, and the code follows from it. With many HTTP APIs, the\ndescription and the code that serves it are two separate things that can drift\napart, and a client is often written by hand from a document. In gRPC, the\n`.proto` file is the one place where a method or a field is defined, and every\nclient and server is generated from it. A change to a message reaches every\nlanguage through the same generator, not through someone rereading a document.\n\nThe encoding is compact, because each field travels as its number and its value\nrather than its name. The price is that a message cannot be fully interpreted\nwithout its `.proto` file, since protocol buffers do not describe themselves,\nand that the format assumes a whole message fits in memory at once. Its own\ndocumentation advises a different solution for data beyond a few megabytes.\n\nStreaming is part of the design rather than an add-on. Calls run as streams on\nHTTP/2 connections, so a server streaming method can keep sending results\nthrough the same machinery as a call that answers once.\n\nTime limits travel with the call. A client sets a deadline, gRPC sends what\nremains of it in the `grpc-timeout` header, and when the time runs out, the\nclient gets `DEADLINE_EXCEEDED` and the server's side of the call is cancelled.\nWhen a server calls another server in turn, some implementations pass the\ndeadline on: Java and Go do it by default, and C++ needs it switched on. Because\nthe deadline crosses each hop as the time remaining rather than as a clock time,\nmachines whose clocks disagree still agree on when to give up.\n\nErrors share one vocabulary. gRPC defines 17 status codes, from 0 `OK` to 16\n`UNAUTHENTICATED`, and they are part of the protocol itself, so a Go client and\na Java server agree on what `NOT_FOUND` or `UNAVAILABLE` means.\n\nAll of this suits traffic between services that one team or one company\ncontrols, where both ends can share the `.proto` files and build from them. It\nsuits the browser less well. The gRPC project's own protocol notes say that\nbrowsers do not expose HTTP/2 framing to scripts and never will, so browser code\nspeaks a separate protocol, gRPC-Web, and in the usual setup a proxy translates\nit into native gRPC.\n\n## What it looks like in practice\n\nHere is a small billing service. One unary method fetches an invoice, and one\nserver streaming method sends a customer's invoices one at a time:\n\n```protobuf\nsyntax = \"proto3\";\n\npackage billing.v1;\n\nservice InvoiceService {\n  rpc GetInvoice(GetInvoiceRequest) returns (Invoice);\n  rpc WatchInvoices(WatchInvoicesRequest) returns (stream Invoice);\n}\n\nmessage GetInvoiceRequest {\n  string invoice_id = 1;\n}\n\nmessage WatchInvoicesRequest {\n  string customer_id = 1;\n}\n\nmessage Invoice {\n  reserved 4;\n  reserved \"discount_code\";\n  string invoice_id = 1;\n  string customer_id = 2;\n  int64 total_cents = 3;\n  string currency = 5;\n}\n```\n\nThe numbers are not default values. They are field numbers, and on the wire they\nidentify each field instead of its name. Numbers from 1 to 15 take one byte to\nencode, so they belong to the fields that are set most often. The two `reserved`\nlines record a field that once existed, number 4 called `discount_code`, so that\nneither can come back for a different field.\n\nFor Python, one command generates `billing_pb2.py` with the message classes and\n`billing_pb2_grpc.py` with the client and server classes:\n\n```sh\npython -m grpc_tools.protoc -Iprotos \\\n  --python_out=. --grpc_python_out=. protos/billing.proto\n```\n\nOne call to `GetInvoice` then looks like this as HTTP/2 frames:\n\n```text\nHEADERS (flags = END_HEADERS)\n:method = POST\n:scheme = https\n:path = /billing.v1.InvoiceService/GetInvoice\n:authority = billing.example.com\nte = trailers\ncontent-type = application/grpc+proto\ngrpc-timeout = 2S\n\nDATA (flags = END_STREAM)\n\u003cLength-Prefixed Message\u003e\n\nHEADERS (flags = END_HEADERS)\n:status = 200\ncontent-type = application/grpc+proto\n\nDATA\n\u003cLength-Prefixed Message\u003e\n\nHEADERS (flags = END_STREAM, END_HEADERS)\ngrpc-status = 0\n```\n\n`2S` means two seconds, and `te = trailers` is there to detect proxies that are\nincompatible with gRPC. If the invoice does not exist, the answer still begins\nwith `:status = 200`, and the last frame carries `grpc-status = 5`, which is\n`NOT_FOUND`, along with a `grpc-message` such as `invoice not found`. A server\nthat fails at once may even send a single `HEADERS` frame with the status in it\nand no message at all.\n\nGenerating both sides from one contract is not unique to gRPC. One project in\nthis site's portfolio\n[generated the API contract from the database out](/portfolio/generated-the-api-contract-from-the-database-out/)\nfor an API described with OpenAPI. The chain starts at the database and runs\noutward: Go types define the API, Huma emits the OpenAPI description from them,\na typed TypeScript client and mock handlers are generated from that description,\nand a contract check in CI fails the build when what the frontend sends no\nlonger matches what the API expects. gRPC builds the same discipline into its\ntoolchain, with the `.proto` file as the single source.\n\n## Where it goes wrong\n\n**A call without a deadline can wait forever.** gRPC sets no deadline by\ndefault, so a client calling a server that has hung can wait for an answer\neffectively forever. Give every call a realistic deadline. In Python, it is the\n`timeout` argument, in seconds:\n\n```python\nimport grpc\n\nimport billing_pb2\nimport billing_pb2_grpc\n\ncredentials = grpc.ssl_channel_credentials()\nwith grpc.secure_channel(\"billing.example.com:443\", credentials) as channel:\n    stub = billing_pb2_grpc.InvoiceServiceStub(channel)\n    request = billing_pb2.GetInvoiceRequest(invoice_id=\"INV-1001\")\n    invoice = stub.GetInvoice(request, timeout=2.0)\n```\n\nWhen the time runs out, the call raises `grpc.RpcError`, and its `code()`\nreturns `grpc.StatusCode.DEADLINE_EXCEEDED`. On the server, gRPC cancels the\ncall with `CANCELLED` once the deadline has passed, but stopping any work the\nhandler has started is up to the service's own code, so a long-running handler\nhas to check for the cancellation and stop by itself.\n\n**A timeout does not mean nothing happened.** Client and server each decide for\nthemselves whether a call succeeded, so a call can complete on the server and\nstill fail on the client with `DEADLINE_EXCEEDED`. Cancelling a call does not\nundo work that has already happened. A client that simply tries again can create\nthe same invoice twice. The protocol does not assume that a call is idempotent\nunless it is marked as such. `UNAVAILABLE` is the code most likely to be\ntemporary and worth retrying with a backoff, but the status code documentation\nwarns that retrying is not always safe for operations that are not idempotent.\nThe same document leaves the choice of codes to retry on to the code that makes\nthe calls.\n\n**A reused field number corrupts data.** A field number cannot change once the\nmessage type is in use. If a field is deleted and its number later goes to a new\nfield, older clients and stored messages decode the new field from bytes that\nmeant something else. The Protocol Buffers guide lists what can follow: parse\nerrors, leaked personal data and corrupted data. Never renumber a field, and\nreserve every deleted number and name, as in the example above.\n\n**Every failure looks like a success to HTTP.** Because gRPC answers with HTTP\nstatus 200 even when a call fails, anything that judges traffic by the HTTP\nstatus alone, such as an access log or an error rate built on status codes,\ncounts failures as successes. The specification has servers answer 415 to\nrequests whose content type is not `application/grpc` for that very reason, so\nthat other HTTP/2 clients do not read a gRPC error as a success. Count\n`grpc-status`, not `:status`.\n\n**Long streams pin their load to one server.** Calls run as streams on a shared\nHTTP/2 connection, and once a stream has started, it cannot be moved to another\nserver. A stream that lives for hours keeps its load where it began, however\nmany servers are added later. Each connection also has a limit on concurrent\nstreams, and when it is reached, further calls wait in the client until a stream\nfinishes. The gRPC performance guide advises streaming only where it brings a\nsubstantial gain in performance or simplicity, and a separate channel for each\narea of high load.\n\n**Big payloads do not fit in one message.** gRPC enforces a maximum message\nsize, and a message larger than the configured limit fails with\n`RESOURCE_EXHAUSTED` on whichever side sends or receives it. Raising the limit\nonly moves the problem, since protocol buffers expect the whole message in\nmemory, and with large data several serialised copies can end up there at once.\nSplit large data into a stream of smaller messages, or move it outside gRPC.\n\n## Further reading\n\n- [Core concepts, architecture and lifecycle](https://grpc.io/docs/what-is-grpc/core-concepts/)\n  — service definitions, the four kinds of method, stubs, deadlines and\n  cancellation.\n- [gRPC over HTTP2](https://github.com/grpc/grpc/blob/master/doc/PROTOCOL-HTTP2.md)\n  — the wire protocol: paths, headers, the message prefix and the status in\n  trailers.\n- [Status Codes](https://grpc.io/docs/guides/status-codes/) — all 17 codes, what\n  each means, and which ones the library itself never produces.\n- [Deadlines](https://grpc.io/docs/guides/deadlines/) — why there is no default,\n  how deadlines reach the server, and how they propagate between services.\n- [Language Guide (proto 3)](https://protobuf.dev/programming-guides/proto3/) —\n  field numbers, reserved fields and the rules for changing a message type\n  safely.\n\n\u003chttps://engineer.company/glossary/grpc/\u003e\n","date_modified":"2026-10-30T02:51:31Z","description":"How a .proto file becomes generated clients and servers that talk over HTTP/2, and the deadlines, field numbers and retries that go wrong.","formats":{"gemtext":"https://engineer.company/glossary/grpc/index.gmi","gopher":"https://engineer.company/glossary/grpc/gophermap","html":"https://engineer.company/glossary/grpc/","json":"https://engineer.company/glossary/grpc/index.json","markdown":"https://engineer.company/glossary/grpc/index.md","pdf":"https://engineer.company/glossary/grpc/index.pdf"},"kind":"page","language":"en","title":"What is gRPC?","url":"https://engineer.company/glossary/grpc/","version":1}