gRPC

Vad det är

gRPC är ett ramverk för fjärrproceduranrop. Ett program anropar en
metod på en server som körs på en annan maskin som om servern vore
ett lokalt objekt, och gRPC för anropet över nätverket i ett eget
protokoll ovanpå HTTP/2 och lämnar tillbaka svaret som ett
returvärde.

Allt börjar med en tjänstedefinition: de metoder som kan anropas
utifrån, med typen för varje begäran och varje svar. Som standard
skrivs den i Protocol Buffers, Googles format med öppen källkod för
att serialisera data oberoende av språk och plattform, i en fil vars
namn slutar på `.proto`. Andra format kan kopplas in, men protocol
buffers är det gRPC använder om inget annat anges. Kompilatorn
`protoc` läser filen tillsammans med ett gRPC-plugin och genererar
kod för båda halvorna. Klienten får en stub, ett lokalt objekt med
samma metoder som tjänsten (i vissa språk kallas den helt enkelt
klienten), och servern får ett gränssnitt att implementera. Eftersom
båda halvorna kommer från samma fil kan en server skriven i Java
svara klienter skrivna i Go, Python eller Ruby.

En metod har en av fyra former. En unär metod tar emot en begäran
och returnerar ett svar, som ett vanligt funktionsanrop. En metod
med serverströmning tar emot en begäran och skickar tillbaka en
ström av svar, en metod med klientströmning gör tvärtom, och en
metod med dubbelriktad strömning låter båda sidor skicka sina
strömmar oberoende av varandra. Inom ett och samma anrop garanterar
gRPC att meddelandena kommer fram i den ordning de skickades.

Under huven körs gRPC över HTTP/2. Varje anrop är en `POST` till en
sökväg som består av tjänstens fullständigt kvalificerade namn och
metodens namn, med innehållstypen `application/grpc`. Varje
meddelande skickas bakom ett prefix på fem byte: en byte som anger
om meddelandet är komprimerat och fyra som anger dess längd.
Anropets utfall är inte HTTP-statusen. Ett svar som gRPC själv
skapar har status 200 även när anropet misslyckas, och det egentliga
resultatet kommer i trailers, huvudfält som skickas efter
meddelandekroppen: `grpc-status` med ett tal och eventuellt
`grpc-message` med en beskrivning av felet.

Det gör gRPC till något helt annat än REST. Ett REST-API namnger
resurser och arbetar med dem genom HTTP:s egna metoder och
statuskoder, oftast med JSON-kroppar som vem som helst kan läsa. Ett
gRPC-API är en lista med metoder med typade, binära meddelanden, och
HTTP/2 är bara transporten under. Dokumentationen för Protocol
Buffers sammanfattar själv sitt format så här: ”som JSON, fast
mindre och snabbare”.

Varför det spelar roll

Kontraktet kommer först och koden följer av det. I många HTTP-API:er
är beskrivningen och koden som levererar API:et två separata saker
som kan glida isär, och en klient skrivs ofta för hand utifrån ett
dokument. I gRPC är `.proto`-filen det enda stället där en metod
eller ett fält definieras, och alla klienter och servrar genereras
från den. En ändring av ett meddelande når alla språk genom samma
generator och inte genom att någon läser om ett dokument.

Kodningen är kompakt eftersom varje fält skickas som sitt nummer och
sitt värde i stället för sitt namn. Priset är att ett meddelande
inte kan tolkas fullt ut utan sin `.proto`-fil, eftersom protocol
buffers inte beskriver sig själva, och att formatet förutsätter att
ett helt meddelande ryms i minnet på en gång. Formatets egen
dokumentation rekommenderar en annan lösning för data som är större
än några megabyte.

Strömning är en del av designen och inte ett tillägg. Anrop körs som
strömmar på HTTP/2-anslutningar, så en metod med serverströmning kan
fortsätta skicka resultat genom samma maskineri som ett anrop som
svarar en gång.

Tidsgränser följer med anropet. En klient sätter en tidsfrist, en
deadline som gRPC kallar det, gRPC skickar det som återstår av den i
huvudfältet `grpc-timeout`, och när tiden tar slut får klienten
`DEADLINE_EXCEEDED` och serverns sida av anropet avbryts. När en
server i sin tur anropar en annan server skickar vissa
implementationer tidsfristen vidare: Java och Go gör det som
standard, medan det måste slås på i C++. Eftersom tidsfristen
passerar varje led som återstående tid och inte som ett klockslag,
ger maskiner vars klockor går olika ändå upp vid samma tidpunkt.

Fel har ett gemensamt ordförråd. gRPC definierar 17 statuskoder,
från 0 `OK` till 16 `UNAUTHENTICATED`, och de är en del av själva
protokollet, så en Go-klient och en Java-server är överens om vad
`NOT_FOUND` eller `UNAVAILABLE` betyder.

Allt detta passar trafik mellan tjänster som ett team eller ett
företag kontrollerar, där båda ändar kan dela `.proto`-filerna och
bygga från dem. Det passar sämre för webbläsaren. gRPC-projektets
egna protokollanteckningar säger att webbläsare inte ger skript
tillgång till ramarna i HTTP/2 och aldrig kommer att göra det, så
kod i webbläsaren talar ett separat protokoll, gRPC-Web, och i den
vanliga uppsättningen översätter en proxy det till vanlig gRPC.

Så ser det ut i praktiken

Här är en liten faktureringstjänst. En unär metod hämtar en faktura
och en metod med serverströmning skickar en kunds fakturor en i
taget:

```protobuf
syntax = "proto3";

package billing.v1;

service InvoiceService {
  rpc GetInvoice(GetInvoiceRequest) returns (Invoice);
  rpc WatchInvoices(WatchInvoicesRequest) returns (stream Invoice);
}

message GetInvoiceRequest {
  string invoice_id = 1;
}

message WatchInvoicesRequest {
  string customer_id = 1;
}

message Invoice {
  reserved 4;
  reserved "discount_code";
  string invoice_id = 1;
  string customer_id = 2;
  int64 total_cents = 3;
  string currency = 5;
}
```

Siffrorna är inte standardvärden. De är fältnummer, och i den binära
kodningen identifierar de varje fält i stället för dess namn. Nummer
1 till 15 tar en byte att koda, så de hör till de fält som oftast är
satta. De två `reserved`-raderna håller reda på ett fält som en gång
fanns, nummer 4 med namnet `discount_code`, så att varken numret
eller namnet kan komma tillbaka som ett annat fält.

För Python genererar ett enda kommando `billing_pb2.py` med
meddelandeklasserna och `billing_pb2_grpc.py` med klient- och
serverklasserna:

```sh
python -m grpc_tools.protoc -Iprotos \
  --python_out=. --grpc_python_out=. protos/billing.proto
```

Ett enskilt anrop till `GetInvoice` ser då ut så här som
HTTP/2-ramar:

```text
HEADERS (flags = END_HEADERS)
i:method = POST		engineer.company	70
i:scheme = https		engineer.company	70
i:path = /billing.v1.InvoiceService/GetInvoice		engineer.company	70
i:authority = billing.example.com		engineer.company	70
te = trailers
content-type = application/grpc+proto
grpc-timeout = 2S

DATA (flags = END_STREAM)
<Length-Prefixed Message>

HEADERS (flags = END_HEADERS)
i:status = 200		engineer.company	70
content-type = application/grpc+proto

DATA
<Length-Prefixed Message>

HEADERS (flags = END_STREAM, END_HEADERS)
grpc-status = 0
```

`2S` betyder två sekunder, och `te = trailers` finns där för att
upptäcka proxyservrar som inte är kompatibla med gRPC. Om fakturan
inte finns börjar svaret ändå med `:status = 200`, och den sista
ramen bär `grpc-status = 5`, som är `NOT_FOUND`, tillsammans med ett
`grpc-message` som `invoice not found`. En server som misslyckas
direkt kan till och med skicka en enda `HEADERS`-ram med statusen
och inget meddelande alls.

Att generera båda sidor från ett kontrakt är inget unikt för gRPC.
Ett projekt i webbplatsens portfölj genererade API-kontraktet utåt
från databasen för ett API som beskrivs med OpenAPI. Kedjan börjar i
databasen och går utåt: Go-typerna definierar API:et, Huma genererar
OpenAPI-beskrivningen utifrån dem, en typad TypeScript-klient och
mock-hanterare genereras från den beskrivningen, och en
kontraktskontroll i CI stoppar bygget när det frontenden skickar
inte längre stämmer med vad API:et förväntar sig. gRPC bygger in
samma disciplin i sin verktygskedja, med `.proto`-filen som enda
källa.

Var det går fel

Ett anrop utan tidsfrist kan vänta för evigt. gRPC sätter ingen
tidsfrist som standard, så en klient som anropar en server som har
hängt sig kan i praktiken vänta på ett svar för evigt. Ge varje
anrop en realistisk tidsfrist. I Python är det argumentet `timeout`,
angivet i sekunder:

```python
import grpc

import billing_pb2
import billing_pb2_grpc

credentials = grpc.ssl_channel_credentials()
with grpc.secure_channel("billing.example.com:443", credentials) as channel:
    stub = billing_pb2_grpc.InvoiceServiceStub(channel)
    request = billing_pb2.GetInvoiceRequest(invoice_id="INV-1001")
    invoice = stub.GetInvoice(request, timeout=2.0)
```

När tiden tar slut kastar anropet `grpc.RpcError`, och undantagets
`code()` returnerar `grpc.StatusCode.DEADLINE_EXCEEDED`. På servern
avbryter gRPC anropet med `CANCELLED` när tidsfristen har passerat,
men det är tjänstens egen kod som måste stoppa det arbete som
hanteraren har satt i gång, så en hanterare som arbetar länge måste
själv kontrollera om anropet har avbrutits och sluta.

En timeout betyder inte att inget har hänt. Klient och server avgör
var för sig om ett anrop lyckades, så ett anrop kan slutföras på
servern och ändå misslyckas hos klienten med `DEADLINE_EXCEEDED`.
Ändringar som gjordes före ett avbrott rullas inte heller tillbaka.
En klient som bara försöker igen kan skapa samma faktura två gånger.
Protokollet antar inte att ett anrop är idempotent om det inte
uttryckligen är markerat så. `UNAVAILABLE` är den kod som oftast är
tillfällig och värd att försöka igen med backoff, men
dokumentationen av statuskoderna varnar för att det inte alltid är
säkert att upprepa operationer som inte är idempotenta. Samma
dokument överlåter åt koden som gör anropen att välja vilka koder
som ska försökas igen.

Ett återanvänt fältnummer förstör data. Ett fältnummer kan inte
ändras när meddelandetypen väl används. Om ett fält tas bort och
dess nummer senare går till ett nytt fält, avkodar äldre klienter
och lagrade meddelanden det nya fältet från byte som betydde något
annat. Guiden för Protocol Buffers räknar upp vad som kan följa:
parsningsfel, läckta personuppgifter och korrupta data. Numrera
aldrig om ett fält, och reservera varje borttaget nummer och namn,
som i exemplet ovan.

Varje fel ser ut som en framgång för HTTP. Eftersom gRPC svarar med
HTTP-status 200 även när ett anrop misslyckas, räknar allt som
bedömer trafik efter HTTP-statusen ensam, till exempel en
åtkomstlogg eller en felfrekvens byggd på statuskoder, fel som
lyckade anrop. Specifikationen ber servrar svara

415 på begäranden vars innehållstyp inte är `application/grpc`, just
av det skälet, så att andra HTTP/2-klienter inte läser ett gRPC-fel
som en framgång. Räkna på `grpc-status`, inte på `:status`.

Långa strömmar binder sin last till en server. Anrop körs som
strömmar på en delad HTTP/2-anslutning, och när en ström väl har
startat kan den inte flyttas till en annan server. En ström som
lever i timmar behåller sin last där den började, hur många servrar
som än läggs till senare. Varje anslutning har också en gräns för
samtidiga strömmar, och när den är nådd väntar ytterligare anrop hos
klienten tills en ström blir klar. Prestandaguiden för gRPC
rekommenderar att strömma bara där det ger en väsentlig vinst i
prestanda eller enkelhet, och en separat kanal för varje område med
hög last.

Stora datamängder ryms inte i ett meddelande. gRPC tillämpar en
maximal meddelandestorlek, och ett meddelande som är större än den
inställda gränsen misslyckas med `RESOURCE_EXHAUSTED` på den sida
som skickar eller tar emot det. Att höja gränsen flyttar bara
problemet, eftersom protocol buffers förväntar sig hela meddelandet
i minnet, och med stora data kan flera serialiserade kopior av det
ligga där samtidigt. Dela upp stora data i en ström av mindre
meddelanden, eller flytta dem utanför gRPC.

Läs mer

  * Core concepts, architecture and lifecycle — tjänstedefinitioner,
de fyra typerna av metoder, stubbar, tidsfrister och avbrytande.

  * gRPC over HTTP2 — protokollet på nätverksnivå: sökvägar,
huvudfält, meddelandeprefixet och statusen i trailers.

  * Status Codes — alla 17 koder, vad var och en betyder och vilka
biblioteket självt aldrig skapar.

  * Deadlines — varför det inte finns något standardvärde, hur
tidsfrister når servern och hur de förs vidare mellan tjänster.

  * Language Guide (proto 3) — fältnummer, reserverade fält och
reglerna för att ändra en meddelandetyp på ett säkert sätt.

hDen här sidan på webben	URL:https://engineer.company/sv/glossary/grpc/	engineer.company	70
