Belajar gRPC - gRPC Unary, Streaming, dan Error Handling Dasar

#Pendahuluan

Kontrak sudah dibangkitkan dan server pertama berjalan. Sekarang saatnya melengkapi kemampuan inti gRPC: keempat pola RPC dan penanganan error yang benar. Dua hal ini membedakan aplikasi gRPC yang sekadar jalan dari yang siap produksi.

Di episode 5 kalian mengimplementasikan unary, server streaming, client streaming, dan bidirectional streaming dalam satu service. Setelah itu kita membahas status code, rich error details, serta deadline dan cancelation — topik yang akan terus muncul sampai akhir series.

#Unary RPC

Unary adalah pola satu-request satu-response. Ini yang sudah kalian tulis di episode 4, dan tetap menjadi pola paling umum untuk operasi seperti membaca satu entitas:

func (s *catalogServer) GetProduct(
    ctx context.Context, in *pb.ProductId,
) (*pb.Product, error) {
    if in.Id == "" {
        return nil, status.Error(codes.InvalidArgument, "id wajib diisi")
    }
    return s.db.Find(in.Id)
}

Perhatikan status.Error(codes.InvalidArgument, "id wajib diisi"): server mengembalikan status code standar, bukan sekadar string. Client bisa membaca kode ini secara terprogram untuk pengambilan keputusan.

#Server Streaming

Server streaming mengirim banyak response untuk satu request — cocok untuk daftar besar yang tidak praktis dikirim sekaligus:

func (s *catalogServer) ListProducts(
    in *pb.ProductQuery, stream pb.CatalogService_ListProductsServer,
) error {
    products, err := s.db.Search(in.Keyword)
    if err != nil {
        return err
    }
    for _, p := range products {
        if err := stream.Send(p); err != nil {
            return err
        }
    }
    return nil
}

Client membaca hasil satu per satu lewat stream.Recv() sampai mendapat io.EOF. Metode stream.Send(p) mengalirkan satu message per iterasi tanpa menunggu seluruh data terkumpul — memori tetap terkendali untuk daftar jutaan baris.

#Client Streaming

Client streaming membalik arahnya: client mengirim banyak pesan, server membalas satu pesan di akhir. Berguna untuk upload atau agregasi batch:

func (s *catalogServer) AddBulk(
    stream pb.CatalogService_AddBulkServer,
) error {
    var count int32
    for {
        p, err := stream.Recv()
        if err == io.EOF {
            return stream.SendAndClose(&pb.BulkResult{AddedCount: count})
        }
        if err != nil {
            return err
        }
        s.db.Upsert(p)
        count++
    }
}

Loop berakhir saat stream.Recv() == io.EOF, menandakan client selesai mengirim. Lalu server mengembalikan satu ringkasan lewat SendAndClose.

#Bidirectional Streaming

Pola terkuat: kedua sisi mengirim dan menerima secara bersamaan. Ini ideal untuk chat, voice, atau pengolahan streaming real-time:

func (s *catalogServer) Search(
    stream pb.CatalogService_SearchServer,
) error {
    for {
        term, err := stream.Recv()
        if err == io.EOF {
            return nil
        }
        if err != nil {
            return err
        }
        for _, hit := range s.db.Search(term.Keyword) {
            if err := stream.Send(hit); err != nil {
                return err
            }
        }
    }
}

Di client, stream.Send dan stream.Recv bisa dipanggil dari goroutine berbeda secara bersamaan. stream.Send(hit) di dalam loop yang sama tetap aman karena alur berurutan dalam satu goroutine.

#Error Handling dan Deadline

#Status Code dan Rich Error Details

Status code memberi sinyal terstruktur; rich error details menambahkan konteks. Standar gRPC memakai google/rpc/error_details.proto:

st := status.New(codes.OutOfRange, "kuota produk terlampaui")
ds, _ := st.WithDetails(
    &errdetails.QuotaFailure{Violations: []*errdetails.QuotaFailure_Violation{
        {Subject: "product:add", Description: "melebihi 1000 item"},
    }},
)
return nil, ds.Err()

Client membaca status.FromError(err) lalu memanggil status.Convert(err) untuk mengekstrak detail. &errdetails.QuotaFailure{...} memberi mesin (dan manusia) konteks yang bisa di-parse.

#Menangani Deadline dan Cancelation

Di sisi client, deadline diatur lewat context:

ctx, cancel := context.WithTimeout(parentCtx, 2*time.Second)
defer cancel()

Di sisi server, periksa cancelation agar kerja tidak diteruskan sia-sia:

select {
case <-ctx.Done():
    return nil, status.FromContextError(ctx.Err()).Err()
default:
}

Saat deadline terlampaui, client menerima DEADLINE_EXCEEDED dan cancelation menyebar ke seluruh chain panggilan. status.FromContextError(ctx.Err()) menerjemahkan error konteks menjadi status code gRPC yang benar.

#Penutup

Inti yang harus dibawa pulang:

• Unary untuk request-response sederhana; server streaming untuk daftar besar.
• Client streaming untuk upload batch; bidirectional untuk komunikasi dua arah real-time.
• Status code adalah bahasa error standar antara client dan server.
• Rich error details menambah konteks yang bisa di-parse mesin.
• Selalu set deadline di client dan hormati cancelation di server.
• io.EOF menandakan akhir stream dari sisi pengirim.

Di episode 6 selanjutnya kita membahas metadata, interceptors, dan lifecycle callbacks — bagaimana mengirim token autentikasi lewat metadata, membangun interceptor di sisi client dan server untuk unary maupun streaming, serta lifecycle callbacks untuk request logging, tracing, dan konteks otorisasi. Pattern inilah yang membuat error handling kalian jadi infrastruktur yang bisa dipakai ulang.