DEV Community

Cover image for ConnectRPC Nedir? Connect Protokolü
Tobias Hoffmann
Tobias Hoffmann

Posted on • Originally published at apidog.com

ConnectRPC Nedir? Connect Protokolü

Tarayıcıdan bir gRPC hizmetini çağırmayı denediyseniz, zorluklarını zaten biliyorsunuzdur. Tarayıcılar HTTP/2 kuyruklarını JavaScript'e açmadığı için ham gRPC ile doğrudan konuşamaz. Klasik çözüm, tarayıcı ile gRPC arka ucunuz arasına Envoy gibi bir proxy koymaktır. ConnectRPC bu katmanı çoğu senaryoda ortadan kaldırır: Protobuf tabanlı, tarayıcıdan çağrılabilen, curl ile test edilebilen ve gRPC ekosistemiyle birlikte çalışabilen API'ler oluşturmanızı sağlar.

Apidog'u bugün deneyin

Bu yazıda ConnectRPC'nin ne olduğunu, Connect protokolünün hangi problemi çözdüğünü, gRPC/gRPC-Web/REST ile nasıl karşılaştırıldığını ve HTTP üzerinden bir Connect isteğinin nasıl göründüğünü uygulama odaklı olarak göreceksiniz. Ayrıca Connect ve gRPC uç noktalarını standart API araçlarıyla nasıl test edebileceğinizi inceleyeceğiz.

ConnectRPC Nedir?

ConnectRPC, Protocol Buffers ile tanımladığınız servislerden tarayıcı uyumlu ve gRPC uyumlu HTTP API'leri üretmeye yarayan bir kütüphane ailesidir.

Temel iş akışı şöyledir:

  1. Servisinizi bir .proto dosyasında tanımlarsınız.
  2. Kod üretimini çalıştırırsınız.
  3. Oluşturulan handler veya client kodunu kullanırsınız.
  4. HTTP üzerinden Connect, gRPC veya gRPC-Web çağrılarını kabul edersiniz.

Connect şu işleri sizin yerinize yönetir:

  • routing
  • serialization
  • compression
  • client üretimi
  • gRPC/gRPC-Web/Connect protokol uyumluluğu

Proje, Protobuf için buf araçlarının arkasındaki şirket olan Buf tarafından oluşturuldu ve şu anda CNCF sandbox projesidir. Bu yüzden Connect, şema-öncelikli Protobuf iş akışına doğal olarak uyar.

Bir ConnectRPC sunucusu aynı anda üç protokolü destekleyebilir:

  • gRPC: akış ve HTTP/2 kuyrukları dahil tam uyumluluk.
  • gRPC-Web: ayrı bir proxy gerektirmeden tarayıcı uyumlu kullanım.
  • Connect: standart HTTP üzerinde çalışan, web ve araçlarla daha kolay test edilen protokol.

Pratik sonuç: aynı servisi hem tarayıcıdan hem CLI'dan hem de gRPC client'larından çağırabilirsiniz.

Connect'in Çözdüğü Sorun

gRPC güçlüdür, hızlıdır ve Protobuf sayesinde tip güvenliği sağlar. Ancak tarayıcı tarafında sorun çıkarır çünkü gRPC, HTTP/2 framing ve trailer mekanizmalarına dayanır.

Tarayıcılar bu düşük seviye HTTP/2 detaylarını JavaScript'e açmadığı için doğrudan ham gRPC çağrısı yapamazsınız. Genellikle mimari şöyle olur:

Browser
  -> gRPC-Web request
  -> Envoy veya benzeri proxy
  -> native gRPC backend
Enter fullscreen mode Exit fullscreen mode

Bu çalışır, ancak ek operasyon yükü getirir:

  • proxy deploy etmeniz gerekir
  • proxy config yönetmeniz gerekir
  • hataları hem proxy hem backend tarafında ayıklamanız gerekir
  • tracing ve log korelasyonu karmaşıklaşabilir

Connect protokolü farklı çalışır. Tekli isteklerde standart HTTP POST kullanır. Bu yüzden tarayıcı, fetch, curl veya standart bir API istemcisi ile doğrudan Connect endpoint'ine istek gönderebilir.

Örnek hedef mimari:

Browser / curl / API client
  -> Connect HTTP endpoint

gRPC client
  -> aynı ConnectRPC sunucusu
Enter fullscreen mode Exit fullscreen mode

Yani tek backend ile hem HTTP dostu Connect çağrılarını hem de gRPC çağrılarını karşılayabilirsiniz.

Connect, gRPC, gRPC-Web ve REST Karşılaştırması

Bu yaklaşımlar benzer problemleri çözer, ancak farklı trade-off'lara sahiptir.

gRPC

gRPC, Protobuf'u HTTP/2 üzerinde binary framing ve trailer mekanizmasıyla kullanır. Verimlidir ve dört streaming modunu destekler:

  • unary
  • server streaming
  • client streaming
  • bidirectional streaming

Ancak tarayıcıdan veya terminalden doğrudan test etmek zordur. Detaylar için gRPC ve HTTP/2'nin birlikte nasıl çalıştığını inceleyebilirsiniz.

gRPC-Web

gRPC-Web, gRPC'nin tarayıcı uyumlu varyantıdır. Protobuf odaklıdır ancak çoğu mimaride gerçek gRPC backend'e köprü kurmak için proxy gerekir.

gRPC-Web'in ne olduğuna dair rehber, bu modelin nerede konumlandığını açıklar.

Connect

Connect, Protobuf şemasını ve gRPC benzeri servis/metot modelini korur, ancak protokolü HTTP/1.1, HTTP/2 ve HTTP/3 üzerinde çalışabilir.

Unary çağrılar için gövde düz JSON veya binary Protobuf olabilir. Yanıtlar da gerçek HTTP status code döndürür.

Bu, Connect endpoint'lerini pratikte REST endpoint'i gibi test edilebilir hale getirir.

REST

REST, kaynak odaklıdır ve şema kullanımı isteğe bağlıdır. En yaygın desteklenen API stilidir, ancak Protobuf'un sunduğu kod üretimi ve katı tip güvenliği varsayılan olarak yoktur.

Karşılaştırma için gRPC vs REST yazısına bakabilirsiniz.

Kısa özet:

gRPC       -> yüksek performans, güçlü streaming, tarayıcıda zor
gRPC-Web   -> tarayıcı uyumlu gRPC, çoğu zaman proxy gerekir
Connect    -> Protobuf + HTTP dostu kullanım + gRPC uyumluluğu
REST       -> evrensel HTTP modeli, şema ve tip güvenliği opsiyonel
Enter fullscreen mode Exit fullscreen mode

Connect, Protobuf ve gRPC'nin yöntem modelini korurken tarayıcı ve CLI deneyimini basitleştirmeyi hedefler.

HTTP Üzerinden Bir Connect İsteği

Connect'i pratik yapan nokta şudur: unary Connect çağrısı normal bir HTTP POST isteğidir.

URL formatı:

/<package>.<Service>/<Method>
Enter fullscreen mode Exit fullscreen mode

Örneğin greet.v1 paketinde GreetService içinde Greet metodu varsa endpoint şu olur:

/greet.v1.GreetService/Greet
Enter fullscreen mode Exit fullscreen mode

JSON gövdeyle çağırmak için:

curl \
  --header "Content-Type: application/json" \
  --data '{"name": "Jane"}' \
  http://localhost:8080/greet.v1.GreetService/Greet
Enter fullscreen mode Exit fullscreen mode

Yanıt:

{"greeting": "Hello, Jane!"}
Enter fullscreen mode Exit fullscreen mode

Bu çağrıda özel gRPC client gerekmez. Binary frame çözmeniz gerekmez. Proxy gerekmez. HTTP konuşan herhangi bir araç isteği inceleyebilir.

Unary Connect çağrıları iki içerik tipiyle kullanılabilir:

  • application/json: okunabilir JSON payload
  • application/proto: daha kompakt binary Protobuf payload

Binary Protobuf göndermek için:

curl \
  --header "Content-Type: application/proto" \
  --data-binary @request.bin \
  http://localhost:8080/greet.v1.GreetService/Greet
Enter fullscreen mode Exit fullscreen mode

Geliştirme sırasında genellikle JSON daha pratiktir. Daha küçük payload istediğinizde binary Protobuf tercih edebilirsiniz. Format seçimiyle ilgili trade-off'lar için Protobuf vs JSON karşılaştırmasına bakabilirsiniz.

Streaming çağrılar ise farklıdır. Şu content type değerlerini kullanırlar:

application/connect+proto
application/connect+json
Enter fullscreen mode Exit fullscreen mode

Streaming mesajları bir envelope içine sarılır:

1 byte flag
4 byte big-endian length
message payload
Enter fullscreen mode Exit fullscreen mode

Unary çağrılar bu envelope'u kullanmadığı için standart HTTP isteğine daha temiz eşlenir.

Dil Desteği ve Buf ile Kod Üretimi

ConnectRPC farklı dillerde implementasyonlar sunar. Go ve TypeScript, tarayıcı ve Node.js için kararlı ve üretime hazırdır. Swift, Kotlin ve Python desteği de mevcuttur; Python beta durumundadır.

Tipik proje akışı:

  1. .proto dosyasını yazın.
  2. buf.gen.yaml içine üretim eklentilerini ekleyin.
  3. buf generate çalıştırın.
  4. Oluşturulan server/client kodunu kullanın.
  5. Handler'ları HTTP server'a bağlayın.

Örnek .proto mantığı:

syntax = "proto3";

package greet.v1;

service GreetService {
  rpc Greet(GreetRequest) returns (GreetResponse);
}

message GreetRequest {
  string name = 1;
}

message GreetResponse {
  string greeting = 1;
}
Enter fullscreen mode Exit fullscreen mode

Go projesinde genellikle iki eklenti kullanılır:

  • protoc-gen-go: Protobuf mesaj tipleri için
  • protoc-gen-connect-go: Connect handler ve client kodu için

Kod üretimi:

buf generate
Enter fullscreen mode Exit fullscreen mode

Bu komut, tip güvenli mesajları ve servis kodlarını üretir. Go tarafında oluşturulan Connect handler'ları standart net/http ile çalışır. Bu yüzden ayrı bir özel server runtime'a mahkum olmazsınız; Connect handler'ını mevcut HTTP router'ınıza ekleyebilirsiniz.

Connect Endpoint'ini curl ile Test Etme

Bir Connect unary endpoint'ini test etmek için minimum kontrol listesi:

  1. HTTP method: POST
  2. URL: /<package>.<Service>/<Method>
  3. Header: Content-Type: application/json
  4. Body: Protobuf mesajının JSON karşılığı

Örnek:

curl -i \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{"name":"Jane"}' \
  http://localhost:8080/greet.v1.GreetService/Greet
Enter fullscreen mode Exit fullscreen mode

-i eklemek HTTP status code ve header'ları da görmenizi sağlar.

Beklenen yanıt örneği:

HTTP/1.1 200 OK
Content-Type: application/json

{"greeting":"Hello, Jane!"}
Enter fullscreen mode Exit fullscreen mode

Hata ayıklarken şu noktaları kontrol edin:

  • Endpoint path .proto içindeki package/service/method ile eşleşiyor mu?
  • Content-Type doğru mu?
  • JSON alan adları Protobuf alanlarıyla uyumlu mu?
  • Sunucu unary Connect çağrılarını kabul ediyor mu?
  • CORS gerekiyorsa tarayıcı ortamında doğru yapılandırılmış mı?

Connect ve gRPC Uç Noktalarını Apidog ile Test Etme

Connect unary çağrıları düz HTTP olduğu için standart API istemcileriyle test edilebilir.

Apidog içinde bir Connect isteği göndermek için:

  1. Yeni HTTP request oluşturun.
  2. Method olarak POST seçin.
  3. URL olarak Connect endpoint'ini girin: 
http://localhost:8080/greet.v1.GreetService/Greet
Enter fullscreen mode Exit fullscreen mode
  1. Header ekleyin: 
Content-Type: application/json
Enter fullscreen mode Exit fullscreen mode
  1. Body alanına JSON mesajı yazın: 
{"name": "Jane"}
Enter fullscreen mode Exit fullscreen mode
  1. İsteği gönderin ve HTTP status code ile JSON yanıtı kontrol edin.

Apidog özel bir Connect client olmak zorunda değildir; Connect'in HTTP yüzeyini kullanır. Bu, curl ile yaptığınız işlemin UI, kayıtlı istekler ve geçmiş desteğiyle yapılmasıdır.

HTTP fiilleriyle ilgili hızlı tekrar için HTTP metotlarının neler olduğuna bakabilirsiniz.

ConnectRPC sunucusu aynı zamanda gRPC konuşabildiği için aynı servisin gRPC tarafını da test edebilirsiniz. Apidog gRPC endpoint'lerini destekler:

  1. .proto dosyasını içe aktarın.
  2. Servis ve metotları görüntüleyin.
  3. Tip güvenli request oluşturun.
  4. gRPC çağrısını gönderin.
  5. Yanıtı ve hata durumlarını inceleyin.

Böylece aynı araçla iki yüzeyi test edebilirsiniz:

  • HTTP dostu Connect endpoint'leri
  • native gRPC endpoint'leri

gRPC tarafı sizin için öncelikliyse gRPC API'leri verimli bir şekilde nasıl test edeceğiniz rehberini inceleyebilirsiniz.

Connect ve gRPC Testlerini CI'a Taşıma

Manuel testler geliştirme sırasında yeterlidir, ancak regresyonları yakalamak için aynı çağrıları otomatik testlere taşımanız gerekir.

Apidog'da Connect ve gRPC çağrılarınızı test senaryosu veya test paketi olarak kaydedebilirsiniz. Ardından Apidog CLI ile CI pipeline içinde çalıştırabilirsiniz.

CLI kurulumu:

npm install -g apidog-cli
Enter fullscreen mode Exit fullscreen mode

Kaydedilmiş bir senaryo veya paketi çalıştırma:

apidog run \
  --access-token "$APIDOG_ACCESS_TOKEN" \
  -t <scenarioOrSuiteId> \
  -e <environmentId> \
  -r cli,html,junit
Enter fullscreen mode Exit fullscreen mode

Bu komutta:

  • --access-token: Apidog erişim token'ı
  • -t: scenario veya suite ID
  • -e: environment ID
  • -r: rapor formatları

Örnek CI kullanımı:

export APIDOG_ACCESS_TOKEN="***"

apidog run \
  --access-token "$APIDOG_ACCESS_TOKEN" \
  -t "$APIDOG_SUITE_ID" \
  -e "$APIDOG_ENV_ID" \
  -r cli,junit
Enter fullscreen mode Exit fullscreen mode

CLI headless çalışır. Node çalıştırabilen herhangi bir CI ortamına eklenebilir. Anlık istek göndermek yerine kayıtlı test senaryolarını çalıştırdığı için Connect ve gRPC endpoint'lerinizde regresyon kontrolü için uygundur.

Detaylı akış için komut satırından API test etmeye yönelik Apidog CLI eğitimine bakabilirsiniz.

Sıkça Sorulan Sorular

ConnectRPC, gRPC ile aynı mı?

Hayır. ConnectRPC, gRPC, gRPC-Web ve Connect protokolünü destekleyen bir framework ailesidir. Connect sunucusu gRPC istemcileriyle birlikte çalışabilir, ancak Connect protokolünün kendisi tarayıcı ve standart HTTP araçları tarafından doğrudan çağrılabilen ayrı bir HTTP tabanlı tasarımdır.

Tarayıcıdan erişmek için hâlâ Envoy gibi bir proxy gerekir mi?

Connect protokolü için hayır. Connect standart HTTP üzerinden çalıştığı için tarayıcı bir Connect sunucusunu çeviri proxy'si olmadan çağırabilir. Proxy genellikle yalnızca tarayıcı trafiğini native gRPC dışında bir şey konuşmayan backend'e köprülemeniz gerektiğinde gerekir.

ConnectRPC hangi dilleri destekliyor?

Go ve TypeScript, tarayıcı ve Node.js için kararlı ve üretime hazırdır. Swift, Kotlin ve Python desteği de vardır; Python beta durumundadır. Bu diller aynı Protobuf şemasından kod üretebilir.

Connect ve buf arasındaki ilişki nedir?

ConnectRPC, Buf tarafından oluşturuldu ve kod üretimi için buf araç zinciriyle çalışır. .proto dosyalarınızdan mesaj, handler ve client kodu üretmek için buf generate komutunu ve ilgili eklentileri kullanırsınız.

Bir Connect endpoint'ini normal API istemcisiyle test edebilir miyim?

Evet. Unary Connect çağrıları JSON veya Protobuf gövdeli HTTP POST istekleridir ve gerçek HTTP status code döndürür. Bu yüzden curl, Apidog veya herhangi bir HTTP istemcisiyle test edilebilir. Apidog ayrıca .proto dosyasını içe aktararak aynı servisin gRPC tarafını da çağırabilir.

Top comments (0)