# gRPC Glossary

The canonical vocabulary for this workspace. Lessons use *these* words. Definitions are
tight (what the term **is**), opinionated, and reuse other glossary terms on purpose.

## The contract

**gRPC**:
A framework for calling a method on a remote server as if it were local, using Protocol
Buffers as the contract and HTTP/2 as the transport.
_Avoid_: RPC framework (too vague), "REST replacement"

**Protocol Buffers (protobuf)**:
The interface definition language (IDL) and binary serialization format gRPC uses to
describe messages and services in a `.proto` file.
_Avoid_: protobuffers, PB (spell it out first)

**`.proto` file**:
The source of truth: it declares messages and services; code generators turn it into
client and server code. In this repo, `protoc` generates Go into `pkg/manabuf/`.
_Avoid_: schema file, IDL file (say ".proto")

**Message**:
A structured record type in a `.proto` — a set of typed, numbered fields. Compiles to a
Go struct.
_Avoid_: object, DTO, payload (the message *is* the payload)

**Field number**:
The integer tag on each message field (`string subject = 1;`). It — not the name — is
what's written on the wire, so numbers must never change once in use.
_Avoid_: field id, tag, index

**Service**:
A named group of RPC methods declared in a `.proto` (`service EmailModifierService { … }`).
Generates a server interface and a client.
_Avoid_: API, controller, interface (reserve "service" for the proto construct)

**Method / RPC**:
A single remote procedure in a service, with one request and one response message type,
and one of the four RPC types.
_Avoid_: endpoint, route, handler (the *handler* is your Go implementation)

**Stub / client**:
The generated client object whose methods make the network call. "Stub" = the local
stand-in for the remote service.
_Avoid_: proxy, SDK

## The four RPC types

**Unary**:
One request → one response. The default; all of our three services' RPCs are unary.
_Avoid_: request/response (that's the shape, "unary" is the name)

**Server streaming**:
One request → a *stream* of responses. In this repo: tom's `Subscribe`.
_Avoid_: server push

**Client streaming**:
A *stream* of requests → one response. In this repo: bob's `UploadAsset`.
_Avoid_: upload RPC

**Bidirectional streaming**:
Streams flowing both ways at once, independently. No example exists in this repo.
_Avoid_: duplex, bidi (spell it out first)

## Transport & lifecycle

**HTTP/2**:
The transport gRPC runs on — one long-lived connection multiplexing many concurrent
streams, with header compression. The reason gRPC can stream and stay efficient.
_Avoid_: HTTP2, h2 (say "HTTP/2")

**Channel / connection**:
The client-side long-lived connection to a server (Go: `grpc.ClientConn` from
`grpc.Dial`). Reused across many calls.
_Avoid_: socket, session

**Status code**:
The outcome of an RPC — `OK` or one of the canonical error codes (`codes.InvalidArgument`,
`NotFound`, `PermissionDenied`, …). The gRPC equivalent of an HTTP status.
_Avoid_: error code (say "status code"), HTTP status

**Metadata**:
Key–value headers sent alongside a request or response (auth token, request id, trace).
Not part of the message. Go: `metadata.MD`.
_Avoid_: headers (ok informally), context values

**Deadline**:
The absolute time by which an RPC must complete, set by the *client* and propagated to the
server via context. Distinct from a per-server timeout.
_Avoid_: timeout (a timeout is a duration; a deadline is a point in time)

## Middleware & security

**Interceptor**:
A function that wraps every RPC to run cross-cutting logic (auth, logging, tracing,
recovery) before/after the handler. gRPC's middleware. Unary and stream variants.
_Avoid_: middleware (ok informally), filter, decorator

**Interceptor chain**:
The ordered list of interceptors an RPC passes through (in this repo: tags → logging →
recovery → timeout → auth → tracing). Order matters.
_Avoid_: pipeline, stack

**RBAC decider**:
Our per-service `map[string][]string` (`rbacDecider`) mapping each full method path to its
allowed roles; the auth interceptor checks the caller's roles against it.
_Avoid_: ACL, permission map

**Claims**:
The identity carried in the JWT and injected into context by the auth interceptor —
`UserID`, `ResourcePath` (tenant), `UserGroup`, roles. Handlers read these, never the
request.
_Avoid_: token data, principal

## Codegen & tooling (repo-specific)

**`protoc`**:
The Protocol Buffers compiler. This repo runs it (via `make gen-proto-go` →
`proto/gen_go.sh`) with the Go + gRPC + gateway plugins to generate `pkg/manabuf/`.
_Avoid_: "the buf generator" (buf does not generate here)

**`buf`**:
A protobuf tool used in this repo **only** for linting and breaking-change detection
(`make lint-proto`), *not* code generation.
_Avoid_: "our codegen" (it isn't)

**grpc-gateway / transcoding**:
A generated reverse proxy that exposes a gRPC service over HTTP/JSON, driven by
`option (google.api.http)` annotations. Mounts under `/{service}/api/v1/proxy/*` (fronts
gandalf).
_Avoid_: REST bridge, JSON API