gRPC և Protocol Buffers

01Գաղափարը՝ remote procedure call-եր պայմանագրով

REST-ի դեպքում մտածում եք ռեսուրսներով և HTTP բայերով՝ GET /orders/42։ gRPC-ի դեպքում մտածում եք ֆունկցիաներով՝ OrderService.GetOrder(id)։ Սա կոչվում է RPC՝ remote procedure call։ Կարևոր տարբերությունը պայմանագիրն է։ gRPC-ում API-ն գրվում է .proto ֆայլում Protocol Buffers-ով (Protobuf)՝ ինտերֆեյսի սահմանման լեզվով։ Կոմպիլյատորը (protoc կամ Buf CLI) այդ ֆայլը վերածում է կոդի՝ հաղորդագրությունների կլասներ, client stub, որը կանչում եք սովորական մեթոդի պես, և server ինտերֆեյս, որը դուք իրականացնում եք։ Եթե սերվերը փոխում է դաշտի տիպը, client-ները, որոնք վերագեներացնում են կոդը, ստանում են կոմպիլյացիայի սխալ՝ production-ում անակնկալի փոխարեն։ .proto ֆայլը պատկերացրեք որպես իրավաբանորեն պարտադիր մենյու, որին պետք է հետևեն և՛ խոհանոցը, և՛ հաճախորդները։

• Protobuf. սխեմայի լեզուն և բինար կոդավորումը։
• Stub. գեներացված client օբյեկտ, որի մեթոդները ցանցային կանչեր են կատարում։
• Channel. երկարատև կապ սերվերի հասցեի հետ։

02.proto ֆայլի գրում

.proto ֆայլը հայտարարում է package, message-ներ (տվյալների կառուցվածքներ) և service-ներ (RPC մեթոդների խմբեր)։ Յուրաքանչյուր դաշտ ունի տիպ և դաշտի համար (field number)։ Ցանցով փոխանցվում է համարը, ոչ թե անունը, ուստի հրապարակելուց հետո այն երբեք չպետք է փոխվի կամ կրկին օգտագործվի։ proto3 շարահյուսությունը տարածված ընտրությունն է. Protobuf-ի ավելի նոր «editions»-ները feature flag-երով միավորում են proto2-ի և proto3-ի վարքագիծը, բայց proto3 ֆայլերը մնում են լիովին աջակցվող։ Ամսաթվերի համար օգտագործեք well-known տիպեր, օրինակ՝ google.protobuf.Timestamp, և յուրաքանչյուր մեթոդի համար պահեք մեկ request և մեկ response message, որպեսզի հետագայում կարողանաք դաշտեր ավելացնել՝ առանց signature-ները կոտրելու։

1syntax = "proto3";
2 
3package shop.orders.v1;
4 
5import "google/protobuf/timestamp.proto";
6 
7service OrderService {
8  rpc GetOrder(GetOrderRequest) returns (GetOrderResponse);
9  rpc WatchOrders(WatchOrdersRequest) returns (stream OrderEvent);
10}
11 
12message GetOrderRequest { string order_id = 1; }
13message GetOrderResponse { Order order = 1; }
14message WatchOrdersRequest { string customer_id = 1; }
15message OrderEvent { Order order = 1; string type = 2; }
16 
17message Order {
18  string id = 1;
19  int64 total_cents = 2;
20  google.protobuf.Timestamp created_at = 3;
21}

03Ներքուստ. HTTP/2, framing և status code-եր

gRPC-ն աշխատում է HTTP/2-ի վրա։ Յուրաքանչյուր կանչ HTTP/2 stream է ընդհանուր TCP կապի վրա, ուստի բազմաթիվ կանչեր մուլտիպլեքսավորվում են առանց HTTP մակարդակում head-of-line blocking-ի։ Հարցումը POST է /package.Service/Method հասցեին՝ content-type application/grpc-ով։ Յուրաքանչյուր հաղորդագրություն երկարության նախածանցով բինար Protobuf է։ Metadata-ն (header-ների նման) կրում է auth token-ներ և tracing ID-ներ։ Արդյունքներն ավարտվում են trailer-ներով, որոնք պարունակում են grpc-status և grpc-message։ gRPC-ն ունի իր սեփական status code-երը՝ HTTP-ից առանձին. OK, INVALID_ARGUMENT, NOT_FOUND, ALREADY_EXISTS, PERMISSION_DENIED, UNAUTHENTICATED, RESOURCE_EXHAUSTED, UNAVAILABLE, DEADLINE_EXCEEDED և այլն։ Client-ները պետք է կրկնեն միայն անվտանգ code-երի դեպքում, օրինակ՝ UNAVAILABLE, և միայն idempotent մեթոդների համար։

1POST /shop.orders.v1.OrderService/GetOrder HTTP/2
2content-type: application/grpc
3te: trailers
4authorization: Bearer <token>
5grpc-timeout: 2S
6 
7<5-byte prefix><binary GetOrderRequest>
8 
9HTTP/2 200
10content-type: application/grpc
11<5-byte prefix><binary GetOrderResponse>
12grpc-status: 0

04RPC-ի չորս տեսակները

gRPC-ն աջակցում է կանչի չորս ձև։ Unary-ն մեկ հարցում և մեկ պատասխան է՝ սովորական ֆունկցիայի պես։ Server streaming-ը ուղարկում է մեկ հարցում և ստանում պատասխանների հոսք. օգտակար է պատվերների live թարմացումների կամ մեծ արդյունքների համար։ Client streaming-ը ուղարկում է հարցումների հոսք և ստանում մեկ պատասխան. օգտակար է telemetry կամ chunk-եր վերբեռնելու համար։ Bidirectional streaming-ը թույլ է տալիս երկու կողմերին էլ ինքնուրույն ուղարկել նույն կանչի վրա. օգտագործվում է chat-ի, համատեղ խմբագրման կամ real-time կառավարման համար։ Մեկ կանչի ներսում stream-երը կարգավորված են, իսկ flow control-ը կատարում է HTTP/2-ը։ Երկարատև stream-երին պետք են keepalive-ներ և վերամիացման տրամաբանություն, որովհետև proxy-ներն ու load balancer-ները փակում են անգործուն կապերը։

• Unary: rpc Get(Req) returns (Res)
• Server streaming: rpc Watch(Req) returns (stream Event)
• Client streaming: rpc Upload(stream Chunk) returns (Summary)
• Bidirectional: rpc Chat(stream Msg) returns (stream Msg)

05Node.js server և client գործնականում

Node.js-ում պաշտոնական իրականացումը @grpc/grpc-js-ն է։ Կարող եք .proto-ն բեռնել runtime-ում @grpc/proto-loader-ով, ինչպես ստորև, կամ նախապես գեներացնել TypeScript կոդ Buf-ով և ts-proto կամ protobuf-es plugin-ներով՝ լիարժեք type safety-ի համար։ Յուրաքանչյուր client կանչ պետք է փոխանցի deadline. առանց դրա կախված սերվերը կարող է ռեսուրսները հավերժ պահել։ Production սերվերներն օգտագործում են TLS (createSsl) կամ plaintext-ով աշխատում են միայն mTLS ապահովող mesh-ի ներսում։

1import * as grpc from "@grpc/grpc-js";
2import * as loader from "@grpc/proto-loader";
3 
4const def = loader.loadSync("orders.proto", { keepCase: false, longs: String });
5const pkg = grpc.loadPackageDefinition(def) as any;
6const Svc = pkg.shop.orders.v1.OrderService;
7 
8const server = new grpc.Server();
9server.addService(Svc.service, {
10  getOrder: (call: any, cb: any) => {
11    if (!call.request.orderId) return cb({ code: grpc.status.INVALID_ARGUMENT, details: "orderId required" });
12    cb(null, { order: { id: call.request.orderId, totalCents: "4200" } });
13  },
14});
15server.bindAsync("0.0.0.0:50051", grpc.ServerCredentials.createInsecure(), () => {});
16 
17const client = new Svc("localhost:50051", grpc.credentials.createInsecure());
18client.getOrder({ orderId: "42" }, { deadline: Date.now() + 2000 }, console.log);

06gRPC-ն բրաուզերում և edge-ում

Բրաուզերները չեն կարող լիովին կառավարել HTTP/2 frame-երը կամ fetch-ով կարդալ trailer-ները, ուստի չեն կարող խոսել native gRPC-ով։ Կա երկու տարածված լուծում։ gRPC-Web-ը մի փոքր տարբեր wire ֆորմատ է, որը proxy-ն (Envoy) թարգմանում է իրական gRPC-ի. այն աջակցում է միայն unary և server streaming։ Connect-ը Buf-ի ավելի նոր պրոտոկոլների ընտանիք է, որի սերվերները միաժամանակ խոսում են gRPC, gRPC-Web և պարզ, HTTP/JSON-ի համար հարմար Connect պրոտոկոլով, ուստի բրաուզերը կարող է կանչել նույն ծառայությունը սովորական fetch-ով։ Շատ թիմեր փոխարենը պահում են REST կամ GraphQL հանրային edge-ում և gRPC-ն օգտագործում միայն դրա հետևում՝ grpc-gateway-ի կամ Envoy-ի նման gateway-ով, որը JSON-ը տրանսկոդավորում է gRPC-ի։

07Գործիքներ և production checklist

Օգտագործեք Buf CLI-ն՝ .proto ֆայլերը lint անելու, CI-ում կոտրող փոփոխությունները հայտնաբերելու և buf.gen.yaml-ից կոդը վերարտադրելի գեներացնելու համար։ Տարբերակավորեք package-ները անվան մեջ (orders.v1, orders.v2)։ Միացրեք ստանդարտ health checking ծառայությունը, որպեսզի load balancer-ները և Kubernetes probe-երը կարողանան ստուգել պատրաստվածությունը, իսկ ոչ production միջավայրերում՝ server reflection, որպեսզի grpcurl-ի նման գործիքները կարողանան ուսումնասիրել API-ն։ Փոխանցեք deadline-ները և tracing metadata-ն (OpenTelemetry) կանչերի միջով։ Հաղորդագրության չափի սահմանները դրեք գիտակցաբար. իրականացումների մեծ մասում ստացման լռելյայն առավելագույն չափը 4 MB է։

1# Lint, check for breaking changes vs main, then generate code
2buf lint
3buf breaking --against ".git#branch=main"
4buf generate
5 
6# Call a running server (needs reflection or the .proto)
7grpcurl -plaintext -d '{"order_id":"42"}' localhost:50051 shop.orders.v1.OrderService/GetOrder
8grpcurl -plaintext localhost:50051 grpc.health.v1.Health/Check

08Protobuf-ի wire ֆորմատը և ինչու է այն փոքր

Յուրաքանչյուր դաշտ կոդավորվում է որպես tag (դաշտի համարը՝ երեք բիթ ձախ տեղաշարժված, գումարած wire type), որին հաջորդում է արժեքը։ Ամբողջ թվերն օգտագործում են varint. փոքր թվերը զբաղեցնում են մեկ բայթ, մեծերը՝ ավելի շատ։ Ահա թե ինչու են 1-ից 15 դաշտերի համարները թանկարժեք. դրանց tag-ը տեղավորվում է մեկ բայթում, ուստի պահեք դրանք հաճախակի դաշտերի համար։ Բացասական թվերը int32/int64-ում միշտ զբաղեցնում են տասը բայթ. հաճախ բացասական արժեքների համար օգտագործեք sint32/sint64 (zigzag կոդավորում)։ String-երը, bytes-ը և ներդրված message-ները length-delimited են։ Լռելյայն արժեքները (0, դատարկ string, false) proto3-ում ընդհանրապես չեն գրվում, եթե դաշտը նշված չէ optional, ահա թե ինչու առանց optional-ի կամ wrapper տիպերի չեք կարող տարբերել «չսահմանված»-ը «զրո»-ից։ Repeated scalar-ները proto3-ում լռելյայն packed են։

1message Reading {
2  int32 sensor_id = 1;        // tag 0x08, varint
3  sint32 delta = 2;           // zigzag: -1 encodes as 1 byte
4  optional double value = 3;  // presence tracked: unset != 0.0
5  repeated int32 samples = 4; // packed into one length-delimited block
6  reserved 5, 6;
7  reserved "legacy_name";
8}

09Load balancing, name resolution և xDS

gRPC channel-ը մեկ կապ չէ. այն կառավարիչ է, որը թիրախային անունը (dns:///orders.internal:50051) լուծում է հասցեների, բացում է subchannel-ներ դրանցից յուրաքանչյուրի հետ և ըստ load-balancing policy-ի յուրաքանչյուր կանչի համար ընտրում մեկը։ Լռելյայն pick_first-ը ամեն ինչ ուղարկում է առաջին առողջ հասցեին. round_robin-ը կանչերը բաշխում է բոլորի միջև։ Service config-ը, որը տրվում է DNS-ով կամ սահմանվում կոդում, կարգավորում է policy-ները, կրկնակի փորձերը և ըստ մեթոդի timeout-ները։ Ավելի մեծ մասշտաբով gRPC client-ները կարող են խոսել xDS-ով՝ Envoy-ի control-plane պրոտոկոլով, և endpoint-ները, կշիռներն ու routing կանոնները ստանալ անմիջապես control plane-ից՝ ստանալով proxyless service mesh-ի վարքագիծ։ Սա խուսափում է sidecar-ի լրացուցիչ hop-ից, բայց client-ներին կապում է mesh-ի control plane-ին։

1// Node.js: client-side round robin + retry policy via service config
2const serviceConfig = JSON.stringify({
3  loadBalancingConfig: [{ round_robin: {} }],
4  methodConfig: [{
5    name: [{ service: "shop.orders.v1.OrderService", method: "GetOrder" }],
6    timeout: "2s",
7    retryPolicy: { maxAttempts: 3, initialBackoff: "0.1s", maxBackoff: "1s",
8      backoffMultiplier: 2, retryableStatusCodes: ["UNAVAILABLE"] },
9  }],
10});
11const client = new Svc("dns:///orders.internal:50051", creds,
12  { "grpc.service_config": serviceConfig });

10Streaming մասշտաբով. flow control և backpressure

HTTP/2 flow control-ը յուրաքանչյուր stream-ի և կապի համար տալիս է բայթերի պատուհան, որը ստացողը պատրաստ է ընդունել։ Եթե client-ը server stream-ը դանդաղ է կարդում, պատուհանը լցվում է, և սերվերի գրառումները արգելափակվում կամ բուֆերացվում են. սա backpressure-ն է, որն աշխատում է ըստ նախագծի։ Խնդիրներ առաջանում են, երբ սերվերի կոդը անտեսում է դա և անսահմանափակ հաղորդագրություններ է բուֆերացնում հիշողությունում։ Node.js-ում հարգեք call.write()-ի վերադարձվող արժեքը և սպասեք 'drain'-ին։ Երկարատև stream-երին պետք են նաև keepalive ping-եր, որպեսզի NAT gateway-ները և proxy-ները լուռ չկտրեն անգործուն կապերը, բայց չափազանց ագրեսիվ keepalive-ների դեպքում client-ը մերժվում է GOAWAY 'too_many_pings'-ով։ Stream-երը նախագծեք վերսկսելի. ներառեք cursor կամ հաջորդականության համար, որպեսզի վերամիացող client-ը կարողանա շարունակել այնտեղից, որտեղ կանգնել էր։

11Անվտանգություն. mTLS, auth և interceptor-ներ

Ծառայությունների միջև mutual TLS-ը տալիս է և՛ գաղտնագրում, և՛ ինքնություն. յուրաքանչյուր workload ունի սերտիֆիկատ, որը հաճախ ավտոմատ թողարկվում է mesh-ի կամ SPIFFE/SPIRE-ի կողմից, և սերվերները կանչողներին թույլտվություն են տալիս ըստ նրանց սերտիֆիկատի ինքնության։ Օգտատիրոջ ինքնությունը փոխանցվում է առանձին՝ որպես bearer token metadata-ում, և վալիդացվում server interceptor-ում, որը gRPC-ի middleware-ն է։ Interceptor-ներում եք ավելացնում նաև լոգավորումը, մետրիկաները, tracing-ը, rate limiting-ը և panic recovery-ն՝ միատեսակ բոլոր մեթոդների համար։ Production-ում անջատեք կամ պաշտպանեք server reflection-ը, սահմանափակեք հաղորդագրությունների առավելագույն չափը՝ հիշողության չարաշահումը կանխելու համար, և մուտքը վալիդացրեք բացահայտ. protovalidate-ը թույլ է տալիս .proto-ում հայտարարել կանոններ, ինչպես string-ի երկարությունը կամ email ֆորմատը, և դրանք պարտադրել գեներացված կոդում։