<?xml version="1.0" encoding="UTF-8"?><rss xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:content="http://purl.org/rss/1.0/modules/content/" xmlns:atom="http://www.w3.org/2005/Atom" version="2.0" xmlns:cc="http://cyber.law.harvard.edu/rss/creativeCommonsRssModule.html">
    <channel>
        <title><![CDATA[Stories by Teoman on Medium]]></title>
        <description><![CDATA[Stories by Teoman on Medium]]></description>
        <link>https://medium.com/@teomangungoren?source=rss-70f0f8c27a2c------2</link>
        <image>
            <url>https://cdn-images-1.medium.com/proxy/1*TGH72Nnw24QL3iV9IOm4VA.png</url>
            <title>Stories by Teoman on Medium</title>
            <link>https://medium.com/@teomangungoren?source=rss-70f0f8c27a2c------2</link>
        </image>
        <generator>Medium</generator>
        <lastBuildDate>Wed, 18 Nov 2026 14:27:05 GMT</lastBuildDate>
        <atom:link href="https://medium.com/@teomangungoren/feed" rel="self" type="application/rss+xml"/>
        <webMaster><![CDATA[yourfriends@medium.com]]></webMaster>
        <atom:link href="http://medium.superfeedr.com/" rel="hub"/>
        <item>
            <title><![CDATA[Claiming Rows Concurrently with PostgreSQL SKIP LOCKED]]></title>
            <link>https://medium.com/@teomangungoren/claiming-rows-concurrently-with-postgresql-skip-locked-8d4b8cf29034?source=rss-70f0f8c27a2c------2</link>
            <guid isPermaLink="false">https://medium.com/p/8d4b8cf29034</guid>
            <category><![CDATA[kotlin]]></category>
            <category><![CDATA[postgresql]]></category>
            <category><![CDATA[distributed-systems]]></category>
            <category><![CDATA[database]]></category>
            <category><![CDATA[spring-boot]]></category>
            <dc:creator><![CDATA[Teoman]]></dc:creator>
            <pubDate>Sat, 17 Oct 2026 14:19:32 GMT</pubDate>
            <atom:updated>2026-10-19T07:08:49.556Z</atom:updated>
            <content:encoded><![CDATA[<p><em>How to safely allocate available coupons under concurrent traffic using Kotlin, Spring Boot, and PostgreSQL.</em></p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*If4QyE7WplBur_Bs0a82Nw.png" /></figure><p>Imagine a loyalty platform where thousands of customers try to earn coupons at the same time.</p><p>Each customer should receive one eligible coupon from a shared pool. Coupons are stored in PostgreSQL, and an unclaimed coupon is identified by earned_by IS NULL.</p><p>The business requirement sounds simple:</p><p>Find an available coupon, assign it to a customer, and ensure that concurrent requests cannot claim the same coupon.</p><p>The challenge is not simply updating a row. It is coordinating the selection and allocation of shared resources under concurrency.</p><p>A common implementation uses JPA and optimistic locking with @Version. This can be correct, but when multiple transactions select the same available coupon, one of them fails with an optimistic locking exception, even though other coupons are still available.</p><p>Could PostgreSQL help us allocate <em>different</em> coupons concurrently instead of making competing transactions fight over the same row?</p><p>Unless stated otherwise, this article assumes PostgreSQL’s default READ COMMITTED isolation level.</p><h3>1. The real problem: selecting and claiming an available coupon</h3><p>Consider this simplified schema:</p><pre>CREATE TABLE coupon_code (<br>    id UUID PRIMARY KEY,<br>    coupon_group_id UUID NOT NULL,<br>    earned_by UUID,<br>    earned_at TIMESTAMPTZ,<br>    version BIGINT NOT NULL DEFAULT 0<br>);</pre><p>A conventional JPA implementation might look like this:</p><pre>@Transactional<br>fun allocateCoupon(<br>    couponGroupId: UUID,<br>    customerId: UUID<br>): CouponCode {<br>    val coupon = repository<br>        .findFirstByCouponGroupIdAndEarnedByIsNull(couponGroupId)<br>        ?: throw NoAvailableCouponException()<br><br>    coupon.earnedBy = customerId<br>    coupon.earnedAt = Instant.now()<br>   <br> return repository.save(coupon)<br>}</pre><p>The important detail is that the query selects <em>an available coupon</em>, not a specific coupon ID supplied by the customer. A “find the first available row” query points every concurrent request at the same row, so collisions are the expected outcome, not an edge case.</p><p>Both transactions can read the same available row before either commits.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*tMXITBnPcsCFnppRxGAhIQ.png" /></figure><p>@Transactional does not automatically serialize these operations. The outcome depends on the isolation level, the generated SQL, and the concurrency control mechanism.</p><p>If the entity uses @Version, Hibernate detects the conflicting update. That protects the row from an undetected stale write, but the losing request may fail even though other available coupons exist.</p><p>For a coupon allocation system, this raises a more interesting question:</p><p>Can we coordinate the selection itself so that concurrent transactions claim different available rows?</p><h3>2. What @Version solves, and what it doesn’t</h3><p>A versioned JPA entity might look like this:</p><pre>@Version<br>var version: Long = 0</pre><p>Hibernate generates an update conceptually equivalent to:</p><pre>UPDATE coupon_code<br>SET earned_by = :customerId,<br>    earned_at = :earnedAt,<br>    version = :oldVersion + 1<br>WHERE id = :couponId<br>  AND version = :oldVersion;</pre><p>Suppose both transactions read version 0.</p><p>The first transaction updates the row and advances its version to 1. The second attempts the same update using version 0, so its update affects no rows. Hibernate detects the conflict and raises an optimistic locking exception.</p><p>This is the intended behavior of optimistic locking: detect conflicting modifications rather than silently overwrite newer state (<a href="https://docs.hibernate.org/orm/current/userguide/html_single/#locking-optimistic">Hibernate ORM: Locking</a>).</p><p>However, optimistic locking does not make the losing transaction select another coupon. A retry might pick a different row, but that requires an explicit retry strategy and another round trip. Repeated retries under heavy contention increase database load and request latency.</p><p>There is an important distinction:</p><ul><li>Optimistic locking <em>detects a conflicting update</em>.</li><li>Coupon allocation <em>determines which available resource a transaction should claim</em>.</li></ul><p>They are related, but they are not the same responsibility.</p><p>Optimistic locking remains useful for ordinary entity updates and for workloads where conflicts are uncommon. For a shared pool of interchangeable coupons, we can also consider a database-driven allocation strategy.</p><h4>What about simply retrying?</h4><p>A common first step is to keep @Version and retry the operation when an OptimisticLockingFailureException occurs, for example with Spring Retry or Resilience4j. The retry must wrap the transactional method from the outside, so that every attempt runs in a new transaction with a fresh persistence context.</p><p>This is a reasonable approach when conflicts are rare. It keeps the code portable and stays within standard JPA. Under high contention, however, it scales poorly: a query like findFirst... points every concurrent request at the same row, so only one transaction wins per round while the others repeat the same collision. Each failed attempt is an extra database round trip, and some requests may exhaust their retries even though many coupons are still available.</p><p>Retrying reacts to a conflict after it happens, while SKIP LOCKED reduces the chance of conflicting in the first place.</p><h3>3. Using FOR UPDATE SKIP LOCKED for concurrent allocation</h3><p>PostgreSQL provides row-level locking through SELECT ... FOR UPDATE. When one transaction locks a row, another transaction trying to lock the same row normally waits. With SKIP LOCKED, PostgreSQL skips rows it cannot lock immediately.</p><p>This is useful for queue-like workloads with multiple concurrent consumers. PostgreSQL explicitly cautions that SKIP LOCKED provides an inconsistent view of the data and is not suitable for general-purpose work, but it can be appropriate for avoiding lock contention in this kind of resource-claiming operation (<a href="https://www.postgresql.org/docs/current/sql-select.html#SQL-FOR-UPDATE-SHARE">PostgreSQL: The Locking Clause</a>).</p><p>The candidate-selection query becomes:</p><pre>SELECT id<br>FROM coupon_code<br>WHERE coupon_group_id = :couponGroupId<br>  AND earned_by IS NULL<br>ORDER BY id<br>LIMIT 1<br>FOR UPDATE SKIP LOCKED;</pre><p>The selected row is locked for the current transaction. Consider a pool of three available coupons:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*GfL9iVQbhkM2sbrRLd5VTw.png" /></figure><p>If enough eligible rows exist, concurrent transactions can claim different coupons without waiting on the same row.</p><p>This is the key benefit: instead of detecting a conflict after competing transactions select the same row, the database coordinates which rows each transaction can claim.</p><p>It is not a guarantee of zero waiting or unlimited throughput. Index contention, other constraints, and the rest of the database workload can still limit concurrency.</p><p>A note on ORDER BY id: a deterministic order makes every transaction start from the same end of the pool, so under very high concurrency each one first walks past rows locked by the others. If your business does not need a specific order, consider whether you need it at all. If it does (for example, earliest expiry first), keep it deliberately. Also note that SKIP LOCKED does not give strict FIFO guarantees.</p><h3>4. Combining selection and assignment in one SQL statement</h3><p>We can go a step further and combine selection, locking, and assignment in a single statement:</p><pre>WITH candidate AS (<br>    SELECT id<br>    FROM coupon_code<br>    WHERE coupon_group_id = :couponGroupId<br>      AND earned_by IS NULL<br>    ORDER BY id<br>    LIMIT 1<br>    FOR UPDATE SKIP LOCKED<br>)<br>UPDATE coupon_code AS c<br>SET earned_by = :customerId,<br>    earned_at = CURRENT_TIMESTAMP,<br>    version = c.version + 1<br>FROM candidate<br>WHERE c.id = candidate.id<br>  AND c.earned_by IS NULL<br>RETURNING<br>    c.id,<br>    c.coupon_group_id,<br>    c.earned_by,<br>    c.version;</pre><p>This statement has three logical stages:</p><ol><li>Find and lock one available coupon.</li><li>Assign it to the requesting customer.</li><li>Return the updated values.</li></ol><p>RETURNING avoids a separate query to fetch the assigned coupon.</p><p>The extra earned_by IS NULL condition on the update makes the eligibility requirement explicit. The row lock coordinates competing allocators, and the update predicate is an additional guard against changing a row that no longer qualifies.</p><p>The statement runs inside a transaction. Its result does not mean the transaction has committed: a later rollback still undoes the assignment.</p><h4>Why not a separate SELECT and UPDATE?</h4><p>A SELECT ... FOR UPDATE SKIP LOCKED followed by an update in the same transaction can also be correct. The combined statement makes the allocation operation easier to isolate, reduces coordination in application code, and returns the resulting state directly.</p><p>The benefit is not that it has fewer lines or must always be faster. Performance depends on indexing, contention, transaction duration, and the actual workload. The stronger argument is that the database owns the critical allocation operation.</p><h3>5. The Kotlin/Spring Boot integration trade-off</h3><p>PostgreSQL supports UPDATE ... RETURNING, but Spring Data JPA’s @Modifying is designed for queries that return an update count or void. It is not meant for mapping the rows an UPDATE returns (<a href="https://docs.spring.io/spring-data/jpa/reference/jpa/query-methods.html#jpa.modifying-queries">Spring Data JPA: Modifying Queries</a>). Fortunately, we don’t need it.</p><p>When a native query is declared with @Query(nativeQuery = true) and without @Modifying, Spring Data executes it as a regular query and reads the result set. PostgreSQL returns a result set for any statement with a RETURNING clause, so the allocation can stay a single atomic statement while the repository returns a lightweight projection instead of a managed entity.</p><p>The projection exposes only what the caller needs:</p><pre>interface CouponAllocationRow {<br>    val id: UUID<br>    val couponGroupId: UUID<br>    val customerId: UUID<br>    val version: Long<br>}</pre><p>The repository declares the allocation statement directly. It is the statement from the previous section, with column aliases so the results map to the projection:</p><pre>interface CouponCodeRepository : JpaRepository&lt;CouponCode, UUID&gt; {<br>   @Query(<br>        value = &quot;&quot;&quot;<br>            WITH candidate AS (<br>                SELECT id<br>                FROM coupon_code<br>                WHERE coupon_group_id = :couponGroupId<br>                  AND earned_by IS NULL<br>                ORDER BY id<br>                LIMIT 1<br>                FOR UPDATE SKIP LOCKED<br>            )<br>            UPDATE coupon_code AS c<br>            SET earned_by = :customerId,<br>                earned_at = CURRENT_TIMESTAMP,<br>                version = c.version + 1<br>            FROM candidate<br>            WHERE c.id = candidate.id<br>              AND c.earned_by IS NULL<br>            RETURNING<br>                c.id,<br>                c.coupon_group_id AS &quot;couponGroupId&quot;,<br>                c.earned_by       AS &quot;customerId&quot;,<br>                c.version<br>        &quot;&quot;&quot;,<br>        nativeQuery = true<br>    )<br>    fun allocateNextAvailable(<br>        couponGroupId: UUID,<br>        customerId: UUID<br>    ): CouponAllocationRow?<br>}</pre><p>Two details matter. There is no @Modifying, and the aliases are quoted, because PostgreSQL folds unquoted aliases to lowercase and the projection properties would not be matched.</p><p>One caveat: returning rows from a DML statement through @Query works in practice with Hibernate and the PostgreSQL driver, but it is not a documented Spring Data contract. Cover it with an integration test against a real PostgreSQL instance (Testcontainers works well).</p><p>The service method that calls this repository is annotated with @Transactional, so the allocation joins the caller’s transaction. If a later step fails, the allocation is rolled back and the coupon becomes available again.</p><h4>What about Hibernate’s persistence context?</h4><p>A native SQL update does not synchronize an entity that Hibernate has already loaded into its first-level cache.</p><p>Suppose the application loads a coupon into the persistence context, then updates it with the native statement. The database contains the new assignment, but the managed entity may still hold the old values. Incrementing version in SQL does not fix that: if Hibernate later flushes the stale state, the version mismatch may cause an optimistic locking exception, and depending on the mapping, stale state can also lead to incorrect behavior. Hibernate owns version management for its managed entities, so modifying that column outside the ORM is something to do deliberately and carefully.</p><p>A practical design keeps the allocation path isolated:</p><ul><li>Execute the claim through a dedicated repository method that returns a projection.</li><li>Avoid loading the same coupon entity into the persistence context during allocation.</li><li>If the workflow must combine this native statement with JPA access to the same rows, define explicit flush/refresh behavior and test it.</li></ul><p>The point is not to avoid JPA altogether. It is to use a database-specific allocation primitive where it provides a meaningful advantage.</p><h3>6. An important edge case: no row returned</h3><p>SKIP LOCKED introduces a subtle behavior.</p><p>Imagine the group contains exactly one available coupon. Transaction A locks it. Transaction B executes the allocation statement and skips that row, so B receives no result, even though the coupon has not been permanently exhausted. If A later rolls back, the coupon becomes available again.</p><p>Therefore:</p><p>No row returned by a SKIP LOCKED allocation query does not necessarily mean that no available coupons exist.</p><p>It means the statement could not claim a matching row at that moment.</p><p>The API must define what to do with this outcome:</p><ul><li>Return a temporary contention result.</li><li>Retry a bounded number of times with backoff and jitter.</li><li>Recheck availability if the API needs to distinguish likely contention from exhaustion.</li><li>Use a waiting lock strategy if waiting is more appropriate than skipping.</li></ul><p>A separate availability check is only a point-in-time observation. Another transaction can change the state immediately afterward. And blindly retrying every empty result can amplify load during contention, so the retry policy should be bounded and aligned with the endpoint’s latency requirements.</p><h3>7. Indexing the available coupon pool</h3><p>The allocation query repeatedly filters by coupon group and availability:</p><pre>WHERE coupon_group_id = :couponGroupId<br>  AND earned_by IS NULL<br>ORDER BY id<br>LIMIT 1</pre><p>A partial index can help:</p><pre>CREATE INDEX idx_coupon_code_available_by_group<br>ON coupon_code (coupon_group_id, id)<br>WHERE earned_by IS NULL;</pre><p>This index contains only rows that satisfy the availability predicate, potentially reducing the index data relevant to the allocation query (<a href="https://www.postgresql.org/docs/current/indexes-partial.html">PostgreSQL: Partial Indexes</a>).</p><p>It is a candidate index, not a universal optimization. Validate it with realistic data distributions and query plans:</p><pre>EXPLAIN (ANALYZE, BUFFERS)<br>SELECT id<br>FROM coupon_code<br>WHERE coupon_group_id = :couponGroupId<br>  AND earned_by IS NULL<br>ORDER BY id<br>LIMIT 1;</pre><p>This inspects the candidate-selection query. Be careful if you run EXPLAIN ANALYZE on the full UPDATE statement: it actually executes the update. Wrap it in a transaction and roll back.</p><p>Benchmark the complete allocation statement under concurrent load. Measure throughput, p95/p99 latency, lock contention, transaction duration, and the frequency of empty allocation results. A fast query plan in isolation does not guarantee high throughput in production.</p><h3>8. Concurrency control is not the same as business correctness</h3><p>Even a correct allocation query does not enforce every business rule.</p><p>Suppose a customer must receive at most one coupon from a given group. That invariant can be enforced at the database level:</p><pre>CREATE UNIQUE INDEX uq_coupon_code_group_customer<br>ON coupon_code (coupon_group_id, earned_by)<br>WHERE earned_by IS NOT NULL;</pre><p>This is appropriate only if the business rule truly permits at most one coupon per customer per group. If multiple coupons are allowed, it would reject valid assignments. When it does fire, the application receives a DataIntegrityViolationException, which should be translated into a business outcome (for example, an HTTP 409: “customer already has a coupon from this group”).</p><p>There is also a separate retry problem: a transaction might commit successfully, but the HTTP response could be lost. If the client repeats the request, the application might allocate another coupon. That is an idempotency problem, not a row-locking problem. If the API promises that retrying the same logical request returns the original allocation, it needs an idempotency strategy, typically backed by a unique key and a persisted result.</p><p>The responsibilities are distinct:</p><ul><li><strong>Row locking</strong> coordinates competing claims on available rows.</li><li><strong>Unique constraints</strong> enforce business invariants at the database level.</li><li><strong>Idempotency</strong> makes retries of the same logical operation safe.</li></ul><p>A production coupon system may need all three.</p><h3>When not to use this approach</h3><p>SKIP LOCKED fits pools of <em>interchangeable</em> rows. It is a poor fit when:</p><ul><li>The customer asks for a specific coupon code (lock that row, or use optimistic locking).</li><li>The business requires strict ordering or fairness.</li><li>The pool is tiny, so most requests would see empty results due to skipping.</li><li>You need to stay database-agnostic.</li></ul><h3>Conclusion</h3><p>Concurrent coupon allocation is a resource-selection problem, not merely a CRUD update.</p><p>JPA with @Version detects conflicting writes, but it does not redirect a losing transaction to another available coupon. PostgreSQL’s FOR UPDATE SKIP LOCKED lets concurrent allocators skip rows already claimed by other transactions, while UPDATE ... RETURNING combines selection and assignment into a single database operation.</p><p>That approach brings its own trade-offs: PostgreSQL-specific SQL, explicit result mapping, persistence-context boundaries, and the distinction between temporary contention and genuine exhaustion.</p><p>The right design depends on the system’s business invariants, transaction boundaries, retry semantics, and measured workload. The goal is not to eliminate concurrency. It is to make concurrent allocation correct, predictable, and efficient.</p><h3>References</h3><ul><li><a href="https://docs.hibernate.org/orm/current/userguide/html_single/#locking-optimistic">Hibernate ORM: Locking</a></li><li><a href="https://www.postgresql.org/docs/current/sql-select.html#SQL-FOR-UPDATE-SHARE">PostgreSQL: The Locking Clause (</a><a href="https://www.postgresql.org/docs/current/sql-select.html#SQL-FOR-UPDATE-SHARE">SELECT ... FOR UPDATE SKIP LOCKED)</a></li><li><a href="https://www.postgresql.org/docs/current/transaction-iso.html">PostgreSQL: Transaction Isolation</a></li><li><a href="https://www.postgresql.org/docs/current/indexes-partial.html">PostgreSQL: Partial Indexes</a></li><li><a href="https://docs.spring.io/spring-data/jpa/reference/jpa/query-methods.html#jpa.modifying-queries">Spring Data JPA: Modifying Queries</a></li><li><a href="https://github.com/spring-projects/spring-retry">Spring Retry</a></li></ul><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=8d4b8cf29034" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[REST to gRPC with Envoy]]></title>
            <link>https://medium.com/dogus-tech-digital-solutions/rest-to-grpc-with-spring-boot-and-envoy-bae8c48971b8?source=rss-70f0f8c27a2c------2</link>
            <guid isPermaLink="false">https://medium.com/p/bae8c48971b8</guid>
            <category><![CDATA[rest-api]]></category>
            <category><![CDATA[kotlin]]></category>
            <category><![CDATA[distributed-systems]]></category>
            <category><![CDATA[spring-boot]]></category>
            <category><![CDATA[grpc]]></category>
            <dc:creator><![CDATA[Teoman]]></dc:creator>
            <pubDate>Sun, 28 Dec 2025 20:00:54 GMT</pubDate>
            <atom:updated>2026-07-09T10:32:04.235Z</atom:updated>
            <content:encoded><![CDATA[<p>In this article, we’ll move from a traditional REST-based Spring Boot setup<br>to a gRPC-based internal architecture, using Envoy as an edge gateway.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*JI31rYNje-F-K7kehafp5g.png" /></figure><h3>1) What is RPC (Remote Procedure Call)?</h3><ul><li>RPC lets one service invoke a function on another service as if it were local.</li><li>gRPC is a modern RPC stack over HTTP/2 with code-generated stubs from proto IDL, plus streaming, header compression, keep-alive, TLS/MTLS.</li><li>RPC means microservices calling each other’s producing actions (e.g., create order, decrease stock) over the network with gRPC.</li></ul><h3>2) Interface Definition Language (IDL) with Protobuf</h3><ul><li>Protobuf .proto files define services and messages once; server and client stubs are generated from this single source.</li><li>Field numbers ensure backward compatibility; unlike JSON keys, they are stable and compact.</li><li>You can also add HTTP annotations for REST mapping.</li></ul><h3>3) What is Protobuf and how .proto files work?</h3><p>Before understanding how gRPC transports data, it’s important to understand <strong>what is being transported</strong>. That data format is <strong>Protocol Buffers (Protobuf)</strong>.</p><h3><strong>Protobuf</strong></h3><p><strong>Protobuf</strong> is a language- and platform-neutral, binary serialization format developed by Google.<br> It defines <strong>how data structures and service contracts are described</strong>, not how they are transported.</p><p>In short:</p><p>Protobuf = <strong>data schema + serialization format</strong></p><ul><li>gRPC = <strong>transport + invocation model</strong> that uses Protobuf by default</li></ul><pre>syntax = &quot;proto3&quot;;<br><br>package order.v1;<br><br>option java_package = &quot;com.example.order.v1&quot;;<br>option java_multiple_files = true;<br><br>message CreateOrderRequest {<br>  string order_id = 1;<br>  int32 quantity = 2;<br>  bool priority = 3;<br>}<br><br>message CreateOrderResponse {<br>  bool success = 1;<br>}<br><br>service OrderService {<br>  rpc CreateOrder(CreateOrderRequest)<br>      returns (CreateOrderResponse);<br>}</pre><p>From this single file, gRPC can generate:</p><ul><li>Java / Kotlin server interfaces</li><li>Java / Kotlin client stubs</li><li>Go, Node, Python, C++, etc.</li><li>No manual DTO duplication. No contract drift.</li></ul><p>Field numbers (tags): the most important part</p><p>Each field has a <strong>field number</strong>:</p><pre>string order_id = 1;<br>int32 quantity  = 2;<br>bool priority   = 3;</pre><p>These numbers are <strong>not array indexes</strong>.<br> They are <strong>tags used in the binary encoding</strong>.</p><p>Protobuf does <strong>not send field names</strong> over the wire.<br> It sends:</p><pre>(tag number + wire type) → value</pre><p>That’s why Protobuf is:</p><ul><li>Smaller</li><li>Faster</li><li>Schema-driven</li></ul><h4>Why tags enable backward compatibility ?</h4><p>Because the wire format depends on <strong>numbers, not names</strong>, Protobuf supports safe evolution.</p><h4>Safe changes</h4><ul><li>Add a new field with a new number</li><li>Rename a field (number stays the same)</li><li>Reorder fields in the file</li></ul><pre>message CreateOrderRequest {<br>  string order_id = 1;<br>  int32 quantity  = 2;<br>  bool priority   = 3;<br>  string note     = 4; // newly added<br>}</pre><p>Old clients:</p><ul><li>Don’t know field 4</li><li>Automatically ignore it</li></ul><p>New clients:</p><ul><li>Can read old messages (field 4 missing → default value)</li></ul><h4>Breaking changes</h4><ul><li>Reusing a field number for another meaning</li><li>Changing field type for the same number</li><li>Removing a field and reusing its number</li></ul><p>Because of this, <strong>field numbers must never be recycled</strong>.</p><h4>How Protobuf encoding stays small</h4><p>Example data:</p><pre>{<br>  &quot;name&quot;: &quot;Teoman&quot;,<br>  &quot;age&quot;: 25,<br>  &quot;isStudent&quot;: false<br>}</pre><p>Protobuf is a <strong>binary, schema-based format</strong>.<br> Client and server already know the schema, so it doesn’t send field names or metadata.</p><p>Each field is encoded as:</p><ul><li><strong>Tag</strong> (field number + type)</li><li><strong>Value</strong> (binary, compact)</li></ul><p>Key reasons it’s small:</p><ul><li>Field names are replaced by <strong>numeric tags</strong></li><li>Numbers use <strong>varint encoding</strong> (small numbers = fewer bytes)</li><li>Default / empty fields are <strong>not sent at all</strong></li><li>No text, whitespace, or punctuation</li></ul><p>This results in <strong>smaller payloads</strong>, <strong>faster parsing</strong>, and <strong>lower CPU/GC cost</strong>.</p><h3>4) JSON vs Protobuf</h3><ul><li>JSON is human-readable but larger and slower to parse.</li><li>Protobuf is binary, typically 40–80% smaller payloads and faster (less CPU).</li><li>gRPC + Protobuf + HTTP/2 improves latency and bandwidth, especially in <strong>high-throughput</strong> or constrained network environments.</li><li>REST/JSON wins on ecosystem and debuggability; browsers need gRPC-Web or a transcoder. This project uses Envoy’s gRPC-JSON transcoder to get REST entry + gRPC backend.</li></ul><pre>{<br> &quot;name&quot; : &quot;John Doe&quot;,<br> &quot;age&quot;: 30,<br> &quot;isStudent&quot;: true   <br>} </pre><pre>message Person {<br> string name = 1;<br> int32  age = 2;<br> bool   is_student = 3; <br>} </pre><ul><li>JSON size: ~40–45 bytes (quotes, keys, punctuation, true text).</li><li>Protobuf size: ~13–15 bytes</li><li>name: 1B tag + 1B length + 8B content ≈ 10B</li><li>age (30): 1B tag + 1B varint ≈ 2B</li><li>isStudent (bool): 1B tag + 1B value ≈ 2B</li></ul><p><strong>Why not REST only?</strong></p><p>REST + JSON works well at the system boundary. For internal service-to-service communication, it becomes inefficient as traffic and service count increase:<br>- Larger payloads<br>- Manual DTO duplication<br>- Weak contract guarantees</p><p>This is where gRPC fits better as an internal protocol.</p><h3>5) What is gRPC?</h3><ul><li>gRPC is a high-performance RPC (Remote Procedure Call) framework developed by Google.</li><li>It is specifically designed for microservice architectures.<br> gRPC’s default IDL (Interface Definition Language) is Protobuf.</li><li>Message structures and services are defined in .proto files.<br> gRPC runs on top of HTTP/2.</li><li>It supports multiplexing (multiple requests over a single connection) and streaming.</li></ul><h3>6) How gRPC works ?</h3><ul><li>You define services/messages in .proto; gRPC generates client stubs and server bases.</li><li>Client stub call → Protobuf encodes the request → framed over HTTP/2 with gRPC headers → sent on a stream.</li><li>Server decodes HTTP/2/gRPC frames → Protobuf-decodes into a typed object → runs your handler → Protobuf-encodes the response → returns on the same stream with gRPC status/trailers.</li><li>Works for unary and streaming (client/server/bidi) because it’s all HTTP/2 streams with repeated Protobuf frames.</li><li>Protobuf is the compact, fast default; if you need JSON at the edge, a transcoder (like Envoy gRPC-JSON) can translate REST/JSON to the same gRPC/Protobuf methods.</li></ul><h3>7) Why do we need a gRPC Gateway?</h3><p>gRPC is optimized for <strong>service-to-service communication</strong>, but:</p><ul><li>Browsers don’t natively support gRPC</li><li>Many external clients speak REST/JSON</li><li>Public APIs are usually REST-based</li><li>Changing all clients to gRPC is not realistic</li></ul><p>A gateway lets you:</p><ul><li>Keep <strong>REST at the edge</strong></li><li>Use <strong>gRPC internally</strong></li><li>Avoid duplicating REST controllers in every service</li></ul><h3>8)Why Envoy as a gRPC Gateway?</h3><p>Envoy is a <strong>high-performance L7 proxy</strong> with first-class gRPC support.</p><p>Key reasons to use Envoy:</p><ul><li>Native <strong>gRPC-JSON Transcoder</strong></li><li>HTTP/1.1 and HTTP/2 support</li><li>Production-grade performance</li><li>TLS / mTLS out of the box</li><li>Observability (metrics, tracing, access logs)</li><li>Acts as a single entry point (API Gateway role)</li></ul><p>With Envoy:</p><ul><li>REST endpoints are defined in <strong>Protobuf</strong></li><li>No REST code in backend services</li><li>One gateway works for all languages and frameworks</li><li>Envoy cleanly separates edge concerns from business logic.</li></ul><figure><img alt="" src="https://cdn-images-1.medium.com/max/804/1*hUj5e2qgWCiJmG12G67iuQ.png" /></figure><p>Envoy:</p><ul><li>Matches REST routes</li><li>Transcodes JSON ↔ Protobuf</li><li>Forwards requests over HTTP/2</li><li>Returns JSON responses</li></ul><p>Backend:</p><ul><li>Only implements gRPC</li><li>No knowledge of REST or HTTP mapping</li></ul><p>Envoy is not just a gRPC-JSON translator. It also acts as an edge proxy. handling cross-cutting concerns such as TLS termination, authentication, rate limiting, retries, timeouts, and observability. This allows backend gRPC services to stay focused purely on business logic.</p><p>Unlike grpc-gateway, which generates a separate Go-based REST proxy per service, Envoy works as a centralized, language-agnostic gateway suitable for production edge deployments.</p><h3>9) Project Architecture Overview</h3><p>Goal: expose REST/JSON at the edge, keep internal comms gRPC.</p><ul><li>Components: Envoy (edge gateway), order-api (gRPC), inventory-api (gRPC), shared proto module (grpc-lib), descriptor.pb fed into Envoy.</li><li>Flow: Client → Envoy (gRPC-JSON transcoder + gRPC-Web) → gRPC services; services talk to DBs.</li></ul><p><strong>Components</strong></p><ul><li>Envoy (edge gateway)</li><li>order-api (gRPC service)</li><li>inventory-api (gRPC service)</li><li>shared proto module (grpc-lib)</li><li>descriptor.pb consumed by Envoy</li></ul><h4>Shared Protobuf Module (grpc-lib)</h4><pre>syntax = &quot;proto3&quot;;<br><br>import &quot;google/api/annotations.proto&quot;;<br><br>option java_multiple_files = true;<br>option java_package = &quot;com.grpc.order_api&quot;;<br>option java_outer_classname = &quot;OrderProto&quot;;<br><br>service OrderService {<br>  rpc createOrder(CreateOrderRequest) returns (CreateOrderResponse) {<br>    option (google.api.http) = {<br>      post: &quot;/orders&quot;<br>      body: &quot;*&quot;<br>    };<br>  }<br>}<br>message CreateOrderRequest {<br>  string productId = 1;<br>  int32 quantity = 2;<br>}<br><br>message CreateOrderResponse {<br>  string orderId = 1;<br>  bool success = 2;<br>  string message = 3;<br>}<br></pre><ul><li>All gRPC contracts are defined in a shared module</li><li><strong>Contains:</strong></li><li>Services</li><li>Messages</li><li>HTTP annotations</li><li><strong>Consumed by:</strong></li><li>Envoy (for REST ↔ gRPC transcoding)</li><li>order-api and inventory-api (generated stubs)</li></ul><p><strong>Why this matters</strong></p><ul><li>Single source of truth</li><li>Contract-first development</li><li>No DTO duplication</li><li>No contract drift</li></ul><h3>Generating descriptor.pb for Envoy</h3><p>Envoy <strong>does not read </strong><strong>.proto files directly</strong>.<br> Instead, it consumes a compiled <strong>FileDescriptorSet</strong>, usually named descriptor.pb.</p><h3>What is descriptor.pb?</h3><p>It is a binary bundle that contains:</p><ul><li>Service definitions</li><li>Message schemas</li><li>HTTP annotations</li><li>Field metadata</li></ul><p>This allows Envoy to:</p><ul><li>Understand REST routes</li><li>Perform JSON ↔ Protobuf transcoding</li><li>Validate request/response structures</li></ul><p><strong>Mapping REST Endpoints to gRPC with HTTP Annotations</strong></p><p>At this point;</p><ul><li>Envoy exposes REST endpoints</li><li>Backend services only implement gRPC</li><li>Envoy must know <strong>how a REST request maps to a gRPC method</strong></li></ul><p>That mapping is defined <strong>inside Protobuf</strong>, using <strong>HTTP annotations</strong>.</p><p>This single annotation defines:</p><ul><li>HTTP method: POST</li><li>REST path: /orders</li><li>Body mapping: entire JSON body → gRPC request message</li></ul><p>Envoy configuration is intentionally verbose.<br><strong>Below is a single-file example showing:<br></strong>- Public HTTP listener<br>- gRPC-JSON transcoding<br>- Routing to multiple gRPC backends</p><p><strong>Key sections:<br></strong>- listeners: public HTTP entrypoint<br>- grpc_json_transcoder: REST → gRPC mapping<br>- clusters: upstream gRPC services (HTTP/2)</p><h4>Envoy Configuration</h4><pre>static_resources:<br>  listeners:<br>    - name: listener_0<br>      address:<br>        socket_address: { address: 0.0.0.0, port_value: 8080 }<br>      filter_chains:<br>        - filters:<br>            - name: envoy.filters.network.http_connection_manager<br>              typed_config:<br>                &quot;@type&quot;: type.googleapis.com/envoy.extensions.filters.network.http_connection_manager.v3.HttpConnectionManager<br>                stat_prefix: ingress_http<br>                codec_type: AUTO<br>                generate_request_id: true<br>                route_config:<br>                  name: local_route<br>                  virtual_hosts:<br>                    - name: backend_services<br>                      domains: [&quot;*&quot;]<br>                      routes:<br>                        - match:<br>                            prefix: &quot;/OrderService/&quot;<br>                          route:<br>                            cluster: order_grpc_cluster<br>                            timeout: 60s<br>                          typed_per_filter_config:<br>                            envoy.filters.http.cors:<br>                              &quot;@type&quot;: type.googleapis.com/envoy.extensions.filters.http.cors.v3.CorsPolicy<br>                              allow_origin_string_match:<br>                                - safe_regex:<br>                                    regex: &quot;.*&quot;<br>                              allow_methods: &quot;GET, PUT, DELETE, POST, OPTIONS&quot;<br>                              allow_headers: &quot;keep-alive, user-agent, cache-control, content-type, content-transfer-encoding, x-accept-content-transfer-encoding, x-accept-response-streaming, x-user-agent, x-grpc-web, grpc-timeout&quot;<br>                              expose_headers: &quot;grpc-status, grpc-message&quot;<br>                              max_age: &quot;1728000&quot;<br><br>                        - match:<br>                            prefix: &quot;/orders&quot;<br>                          route:<br>                            cluster: order_grpc_cluster<br>                            timeout: 60s<br><br>                        - match:<br>                            prefix: &quot;/InventoryService/&quot;<br>                          route:<br>                            cluster: inventory_grpc_cluster<br>                            timeout: 60s<br>                          typed_per_filter_config:<br>                            envoy.filters.http.cors:<br>                              &quot;@type&quot;: type.googleapis.com/envoy.extensions.filters.http.cors.v3.CorsPolicy<br>                              allow_origin_string_match:<br>                                - safe_regex:<br>                                    regex: &quot;.*&quot;<br>                              allow_methods: &quot;GET, PUT, DELETE, POST, OPTIONS&quot;<br>                              allow_headers: &quot;keep-alive, user-agent, cache-control, content-type, content-transfer-encoding, x-accept-content-transfer-encoding, x-accept-response-streaming, x-user-agent, x-grpc-web, grpc-timeout&quot;<br>                              expose_headers: &quot;grpc-status, grpc-message&quot;<br>                              max_age: &quot;1728000&quot;<br><br>                        - match:<br>                            prefix: &quot;/inventory&quot;<br>                          route:<br>                            cluster: inventory_grpc_cluster<br>                            timeout: 60s<br><br>                access_log:<br>                  - name: envoy.access_loggers.stdout<br>                    typed_config:<br>                      &quot;@type&quot;: type.googleapis.com/envoy.extensions.access_loggers.stream.v3.StdoutAccessLog<br>                      log_format:<br>                        json_format:<br>                          start_time: &quot;%START_TIME%&quot;<br>                          method: &quot;%REQ(:method)%&quot;<br>                          path: &quot;%REQ(:path)%&quot;<br>                          authority: &quot;%REQ(:authority)%&quot;<br>                          upstream_cluster: &quot;%UPSTREAM_CLUSTER%&quot;<br>                          upstream_host: &quot;%UPSTREAM_HOST%&quot;<br>                          response_code: &quot;%RESPONSE_CODE%&quot;<br>                          grpc_status: &quot;%GRPC_STATUS%&quot;<br>                          duration_ms: &quot;%DURATION%&quot;<br>                          request_id: &quot;%REQ(x-request-id)%&quot;<br><br>                http_filters:<br>                  - name: envoy.filters.http.grpc_json_transcoder<br>                    typed_config:<br>                      &quot;@type&quot;: type.googleapis.com/envoy.extensions.filters.http.grpc_json_transcoder.v3.GrpcJsonTranscoder<br>                      proto_descriptor: &quot;/etc/envoy/descriptor.pb&quot;<br>                      services:<br>                        - &quot;OrderService&quot;<br>                        - &quot;InventoryService&quot;<br>                      print_options:<br>                        add_whitespace: true<br>                        always_print_primitive_fields: true<br>                        preserve_proto_field_names: true<br><br>                  - name: envoy.filters.http.grpc_web<br>                    typed_config:<br>                      &quot;@type&quot;: type.googleapis.com/envoy.extensions.filters.http.grpc_web.v3.GrpcWeb<br><br>                  - name: envoy.filters.http.cors<br>                    typed_config:<br>                      &quot;@type&quot;: type.googleapis.com/envoy.extensions.filters.http.cors.v3.Cors<br><br>                  - name: envoy.filters.http.router<br>                    typed_config:<br>                      &quot;@type&quot;: type.googleapis.com/envoy.extensions.filters.http.router.v3.Router<br><br>  clusters:<br>    - name: order_grpc_cluster<br>      connect_timeout: 5s<br>      type: STRICT_DNS<br>      dns_lookup_family: V4_ONLY<br>      lb_policy: ROUND_ROBIN<br>      typed_extension_protocol_options:<br>        envoy.extensions.upstreams.http.v3.HttpProtocolOptions:<br>          &quot;@type&quot;: type.googleapis.com/envoy.extensions.upstreams.http.v3.HttpProtocolOptions<br>          explicit_http_config:<br>            http2_protocol_options: {}<br><br>      load_assignment:<br>        cluster_name: order_grpc_cluster<br>        endpoints:<br>          - lb_endpoints:<br>              - endpoint:<br>                  address:<br>                    socket_address:<br>                      address: &quot;order-api-host&quot;<br>                      port_value: 9091<br><br>    - name: inventory_grpc_cluster<br>      connect_timeout: 5s<br>      type: STRICT_DNS<br>      dns_lookup_family: V4_ONLY<br>      lb_policy: ROUND_ROBIN<br>      typed_extension_protocol_options:<br>        envoy.extensions.upstreams.http.v3.HttpProtocolOptions:<br>          &quot;@type&quot;: type.googleapis.com/envoy.extensions.upstreams.http.v3.HttpProtocolOptions<br>          explicit_http_config:<br>            http2_protocol_options: {}<br><br>      load_assignment:<br>        cluster_name: inventory_grpc_cluster<br>        endpoints:<br>          - lb_endpoints:<br>              - endpoint:<br>                  address:<br>                    socket_address:<br>                      address: &quot;inventory-api-host&quot;<br>                      port_value: 9090<br><br></pre><p>In this architecture, Envoy acts as the <strong>edge gateway</strong>.<br> It exposes <strong>REST/JSON and gRPC-Web</strong> externally while keeping <strong>all internal service-to-service communication strictly gRPC</strong>.</p><p>Envoy responsibilities:</p><ul><li>Accept REST/JSON requests</li><li>Transcode JSON ↔ Protobuf</li><li>Bridge HTTP/1.1 ↔ HTTP/2</li><li>Route traffic to gRPC backends</li><li>Provide logging, tracing, and CORS</li></ul><p><strong>Listener: Public Entry Point</strong></p><pre>listeners:<br>  - name: listener_0<br>    address:<br>      socket_address: { address: 0.0.0.0, port_value: 8080 }</pre><ul><li>Envoy listens on port <strong>8080</strong></li><li>All external clients connect here</li><li>gRPC backend services are <strong>not exposed publicly</strong></li></ul><p>Envoy is the <strong>single ingress point</strong> for the system.</p><p><strong>HTTP Connection Manager</strong></p><pre>envoy.filters.network.http_connection_manager</pre><p>This component manages the full HTTP request lifecycle:</p><ul><li>Routing</li><li>Filter execution</li><li>Logging</li><li>Protocol negotiation</li></ul><p>Key settings:</p><ul><li>codec_type: AUTO → supports both HTTP/1.1 and HTTP/2</li><li>generate_request_id: true → enables distributed tracing</li></ul><p><strong>Routing: REST and gRPC Side by Side</strong></p><pre>- match:<br>    prefix: &quot;/orders&quot;<br>  route:<br>    cluster: order_grpc_cluster<br><br>- match:<br>    prefix: &quot;/OrderService/&quot;<br>  route:<br>    cluster: order_grpc_cluster</pre><p>This enables <strong>two access patterns</strong> for the same backend service.</p><p><strong>REST access</strong></p><pre>POST /orders</pre><ul><li>JSON request</li><li>Transcoded to gRPC</li><li>Routed to OrderService.CreateOrder</li></ul><p><strong>Native gRPC access</strong></p><pre>/OrderService/CreateOrder</pre><ul><li>Used by gRPC clients</li><li>No transcoding</li><li>Direct HTTP/2 call</li></ul><p>One service, multiple entry styles.</p><p><strong>gRPC–JSON Transcoder</strong></p><pre>envoy.filters.http.grpc_json_transcoder</pre><pre>proto_descriptor: &quot;/etc/envoy/descriptor.pb&quot;<br>services:<br>  - &quot;OrderService&quot;<br>  - &quot;InventoryService&quot;</pre><p>This filter enables:</p><ul><li>JSON → Protobuf conversion</li><li>REST → gRPC method mapping</li><li>HTTP/1.1 → HTTP/2 upgrade</li></ul><p>All routing and request mapping are driven entirely by <strong>Protobuf contracts</strong><br> (HTTP annotations inside .proto files).</p><p>Envoy does not know your business logic — it only understands your contracts.</p><p><strong>gRPC-Web Support (Browser Clients)</strong></p><pre>envoy.filters.http.grpc_web</pre><ul><li>Browsers cannot speak native gRPC</li><li>gRPC-Web acts as a compatibility layer</li><li>Frontend → Envoy → gRPC backend</li></ul><p>This allows:</p><ul><li>SPA applications</li><li>Web clients</li><li>HTTP/1.1 environments<br> to call gRPC services transparently.</li></ul><p><strong>CORS Handling at the Edge</strong></p><pre>envoy.filters.http.cors</pre><p>CORS is handled:</p><ul><li>Centrally at Envoy</li><li>Not duplicated across services</li><li>Without polluting backend code</li></ul><p>Includes:</p><ul><li>Preflight (OPTIONS)</li><li>Allowed headers</li><li>Allowed methods</li></ul><p><strong>Router Filter</strong></p><pre>envoy.filters.http.router</pre><p>This is the final filter in the chain:</p><ul><li>Resolves the target cluster</li><li>Applies load balancing</li><li>Forwards the request upstream</li></ul><p><strong>Access Logging &amp; Observability</strong></p><pre>access_log:<br>  - envoy.access_loggers.stdout</pre><p>Structured JSON logs include:</p><ul><li>Request path</li><li>Response code</li><li>gRPC status</li><li>Request duration</li><li>Request ID</li></ul><p>This integrates naturally with:</p><ul><li>ELK</li><li>Loki</li><li>Datadog</li><li>OpenTelemetry pipelines</li></ul><h4><strong>End-to-End Flow: OrderService → InventoryService</strong></h4><p><strong>Step 1: Client Sends REST Request</strong></p><pre>POST /orders<br><br>{<br>  &quot;productId&quot;: &quot;d538067a-6545-4530-b86a-c7f375bffa14&quot;,<br>  &quot;quantity&quot;: 2<br>}</pre><p><strong>Step 2: Envoy Transcodes REST → gRPC</strong></p><p>Envoy:</p><ul><li>Matches /orders</li><li>Uses HTTP annotations</li><li>Converts JSON → CreateOrderRequest</li><li>Sends HTTP/2 gRPC request to order-api</li></ul><p><strong>Step 3: OrderService Handles Business Logic</strong></p><pre>@GrpcService<br>class OrderService(<br>    private val orderRepository: OrderRepository,<br>    private val inventoryClient: InventoryServiceGrpc.InventoryServiceBlockingStub<br>)</pre><p>OrderService:</p><ol><li>Validates input</li><li>Calls InventoryService via <strong>gRPC client stub</strong></li><li>Persists the order</li><li>Returns gRPC response</li></ol><pre>inventoryClient.decreaseStock(<br>    DecreaseStockRequest.newBuilder()<br>        .setProductId(productId.toString())<br>        .setQuantity(request.quantity)<br>        .build()<br>)</pre><p>Important:</p><ul><li>This is <strong>service-to-service gRPC</strong></li><li>No Envoy in between</li><li>Pure Protobuf over HTTP/2</li></ul><p><strong>Step 4: Response Propagates Back to Client</strong></p><pre>InventoryService → OrderService → Envoy → Client</pre><p>Envoy:</p><ul><li>Converts Protobuf → JSON</li><li>Preserves HTTP semantics</li><li>Returns REST-friendly response</li></ul><p>Client never knows gRPC exists.</p><h3>10-Logging &amp; Interceptors (Cross-Cutting Concerns)</h3><p>To support observability and tracing, gRPC interceptors are used.</p><pre>@GrpcGlobalServerInterceptor<br>class LoggingServerInterceptor : ServerInterceptor {<br><br>    private val log = LoggerFactory.getLogger(LoggingServerInterceptor::class.java)<br>    private val requestIdKey = Metadata.Key.of(&quot;x-request-id&quot;, Metadata.ASCII_STRING_MARSHALLER)<br><br>    override fun &lt;ReqT : Any, RespT : Any&gt; interceptCall(<br>        call: ServerCall&lt;ReqT, RespT&gt;,<br>        headers: Metadata,<br>        next: ServerCallHandler&lt;ReqT, RespT&gt;<br>    ): ServerCall.Listener&lt;ReqT&gt; {<br>        val start = System.currentTimeMillis()<br>        val requestId = headers[requestIdKey] ?: UUID.randomUUID().toString()<br>        val peer = call.attributes.get(Grpc.TRANSPORT_ATTR_REMOTE_ADDR)<br>        MDC.put(&quot;requestId&quot;, requestId)<br>        log.info(<br>            &quot;gRPC server -&gt; {} peer={} requestId={}&quot;,<br>            call.methodDescriptor.fullMethodName,<br>            peer,<br>            requestId<br>        )<br><br>        val forwardingCall = object : SimpleForwardingServerCall&lt;ReqT, RespT&gt;(call) {<br>            override fun close(status: Status, trailers: Metadata) {<br>                val duration = System.currentTimeMillis() - start<br>                trailers.put(requestIdKey, requestId)<br>                log.info(<br>                    &quot;gRPC server &lt;- {} status={} durationMs={} peer={} requestId={}&quot;,<br>                    call.methodDescriptor.fullMethodName, status.code, duration, peer, requestId<br>                )<br>                super.close(status, trailers)<br>                MDC.remove(&quot;requestId&quot;)<br>            }<br>        }<br><br>        return object : SimpleForwardingServerCallListener&lt;ReqT&gt;(next.startCall(forwardingCall, headers)) {}<br>    }<br>}</pre><p>This interceptor:</p><ul><li>Extracts x-request-id</li><li>Propagates request context</li><li>Logs method name, caller, duration</li><li>Attaches request ID to trailers</li></ul><h3>Why this is important</h3><ul><li>Distributed tracing</li><li>Correlating REST ↔ gRPC calls</li><li>Debugging production issues</li><li>Works independently of Envoy logging</li></ul><p>Envoy handles <strong>edge-level logs</strong>,<br> gRPC interceptors handle <strong>service-level logs</strong>.</p><h3><strong>Conclusion</strong></h3><p>This architecture is not about replacing REST with gRPC.<br> It’s about using each where it fits best.</p><p>REST remains the right choice at the edge:</p><ul><li>broad client support</li><li>easy debugging</li><li>strong ecosystem</li></ul><p>gRPC is a better fit for internal service-to-service communication:</p><ul><li>explicit, strongly typed contracts</li><li>smaller and faster payloads</li><li>HTTP/2 multiplexing and streaming</li></ul><p>Envoy makes this combination viable by acting as a true edge gateway.<br> It centralizes cross-cutting concerns (TLS, routing, CORS, observability) and allows backend services to stay gRPC-only, driven by a single Protobuf contract.</p><h3>Trade-offs</h3><p>This approach is not free:</p><ul><li>higher upfront complexity</li><li>Protobuf and Envoy require operational discipline</li><li>Debugging is more structured and tool-oriented compared to REST.</li></ul><p>It’s not ideal for small systems or short-lived projects.</p><h3>When to Use It</h3><p>This architecture makes sense when:</p><ul><li>APIs are long-lived and shared</li><li>backward compatibility matters</li><li>performance and latency are real concerns</li><li>teams value contract-first development</li></ul><p>REST at the edge, gRPC in the core, Protobuf as the contract.<br>Clear boundaries, predictable evolution, and fewer surprises over time.</p><p><strong>Source code: </strong><a href="https://github.com/teomangungoren/grpc">https://github.com/teomangungoren/grpc</a></p><p><a href="https://www.envoyproxy.io/docs/envoy/latest/configuration/http/http_filters/grpc_json_transcoder_filter">https://www.envoyproxy.io/docs/envoy/latest/configuration/http/http_filters/grpc_json_transcoder_filter</a></p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=bae8c48971b8" width="1" height="1" alt=""><hr><p><a href="https://medium.com/dogus-tech-digital-solutions/rest-to-grpc-with-spring-boot-and-envoy-bae8c48971b8">REST to gRPC with Envoy</a> was originally published in <a href="https://medium.com/dogus-tech-digital-solutions">Doğuş Technology</a> on Medium, where people are continuing the conversation by highlighting and responding to this story.</p>]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Dual Write Problem: Challenges and Solution Approaches]]></title>
            <link>https://medium.com/dogus-tech-digital-solutions/dual-write-problem-challenges-and-solution-approaches-242620c9ceb2?source=rss-70f0f8c27a2c------2</link>
            <guid isPermaLink="false">https://medium.com/p/242620c9ceb2</guid>
            <category><![CDATA[data-consistency]]></category>
            <category><![CDATA[event-driven-architecture]]></category>
            <category><![CDATA[outbox-pattern]]></category>
            <category><![CDATA[dual-write]]></category>
            <category><![CDATA[distributed-systems]]></category>
            <dc:creator><![CDATA[Teoman]]></dc:creator>
            <pubDate>Sun, 29 Dec 2024 12:33:39 GMT</pubDate>
            <atom:updated>2025-01-07T10:15:49.277Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*Wo0fkMn7idIShSvTSSVWmw.png" /><figcaption><a href="https://learn.microsoft.com/en-us/azure/architecture/databases/guide/transactional-outbox-cosmos">https://learn.microsoft.com/en-us/azure/architecture/databases/guide/transactional-outbox-cosmos</a></figcaption></figure><p>The Dual Write Problem arises in distributed systems when there is a need to write data to multiple storage systems simultaneously. This often occurs in microservice architectures or when synchronizing multiple data stores (e.g., a database and a message queue).</p><p>In a scenario where a single operation requires writing to two different locations (e.g., two databases or a database and a message queue), the following issues may arise:</p><p><strong>First Write Succeeds, Second Write Fails</strong>: The first data store is updated successfully, but the second write operation fails.</p><p>Result: Inconsistency between the two data stores.</p><p><strong>Partial Failures</strong>:One of the write operations remains incomplete due to system failures (e.g., network issues or application crashes).</p><p>Result: Data inconsistency.</p><p><strong>Race Conditions</strong>: The two write operations may complete in different orders,leading to unexpected system behavior.</p><p><strong>Can we solve this by publishing the event first ?</strong></p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*AniNxUnJ8BqA7zPuNN8Elw.png" /><figcaption>Event first</figcaption></figure><p>If an error occurs while sending the event, the database transaction will not be executed either. However, in this scenario, if an error occurs during the database transaction, the event cannot be rolled back — it’s already too late.Different consumers may have already consumed the event and successfully completed their local transactions. Therefore, this method does not eliminate the risk of data inconsistency either.</p><p><strong>The Listen To Yourself Pattern</strong></p><p>The listen-to-yourself pattern, like event sourcing, prioritizes writing the event first. Unlike event sourcing, which stores events in a database before publishing to Kafka, this pattern sends events directly to Kafka without updating the database.</p><p>A separate listener process asynchronously updates the database and retries if needed. This creates an eventual consistency model, where a brief delay may cause outdated database states, leading to unexpected results.If eventual consistency is acceptable, this approach is fast and efficient. It solves the dual-write problem by separating processes and enables rapid command responses by deferring most processing.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*0vSNPm99z644cqLHC_7Cjg.png" /><figcaption>The listen-to-yourself pattern</figcaption></figure><p><strong>Transactional Outbox Pattern</strong></p><p>The transactional outbox pattern addresses the dual-write problem by combining database transactions with a retry mechanism.</p><p>An outbox table is added to the database to store events for delivery (e.g., to Kafka). When an OrderCreated command is issued, the database update and event insertion into the outbox table occur within the same transaction, ensuring atomicity.</p><p>A separate process reads events from the outbox, publishes them to Kafka, and retries on failure. Successfully delivered events are marked complete or deleted. This process can be implemented manually(polling publisher) or automated(Transaction Log Tailing) using change data capture (CDC) tools if supported by the database.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*YOLHJL6jqEJQIcsnLhya1Q.png" /><figcaption>Transactional Outbox Pattern</figcaption></figure><p><strong>Conclusion</strong></p><p>In tackling the Dual Write Problem, we’ve explored several approaches to mitigate challenges related to data consistency, latency, and synchronization between different systems. Key strategies like the <strong>Transactional Outbox pattern</strong>, careful <strong>event ordering</strong>, and leveraging <strong>event listeners </strong>provide a robust foundation for addressing common pitfalls in distributed architectures. However, it’s essential to remember that there is no one-size-fits-all solution. Depending on the complexity and specific needs of the system, combining multiple approaches or introducing additional safeguards might be necessary.</p><p>The dual-write problem can arise in any distributed system, including monolithic applications with databases, email servers, or Kafka. Many teams overlook this issue, either because they’re unaware of it or assume it only affects more complex systems. However, even in transactional databases or monolithic applications, the dual-write problem can emerge. Most applications will encounter it at some point, and the challenge lies in recognizing it when it does.</p><p><strong>Resources</strong></p><p><a href="https://www.baeldung.com/cs/outbox-pattern-microservices">https://www.baeldung.com/cs/outbox-pattern-microservices</a></p><p><a href="https://microservices.io/patterns/data/transactional-outbox.html">https://microservices.io/patterns/data/transactional-outbox.html</a></p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=242620c9ceb2" width="1" height="1" alt=""><hr><p><a href="https://medium.com/dogus-tech-digital-solutions/dual-write-problem-challenges-and-solution-approaches-242620c9ceb2">Dual Write Problem: Challenges and Solution Approaches</a> was originally published in <a href="https://medium.com/dogus-tech-digital-solutions">Doğuş Technology</a> on Medium, where people are continuing the conversation by highlighting and responding to this story.</p>]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[How does Elasticsearch ensure consistency when writing data?]]></title>
            <link>https://medium.com/dogus-tech-digital-solutions/how-does-elasticsearch-ensure-consistency-when-writing-data-22d47ad33f25?source=rss-70f0f8c27a2c------2</link>
            <guid isPermaLink="false">https://medium.com/p/22d47ad33f25</guid>
            <category><![CDATA[elasticsearch]]></category>
            <category><![CDATA[software-development]]></category>
            <category><![CDATA[apache]]></category>
            <category><![CDATA[database]]></category>
            <category><![CDATA[software-engineering]]></category>
            <dc:creator><![CDATA[Teoman]]></dc:creator>
            <pubDate>Sun, 01 Dec 2024 18:09:40 GMT</pubDate>
            <atom:updated>2025-01-07T10:16:14.040Z</atom:updated>
            <content:encoded><![CDATA[<p>Elasticsearch, as a distributed system, provides robust mechanisms to ensure consistency for write operations. Data synchronization between primary shards and replica shards is critical for preventing data loss and building a fault-tolerant architecture. In this article, we will examine how consistency is achieved through fundamental concepts such as primary terms and sequence numbers.</p><p>In Elasticsearch, an index is divided into primary shards, and each primary shard can have multiple replica copies. However, there can only be one primary shard per subdivision. The primary shard handles indexing operations, such as adding or deleting documents, and then replicates these changes to the replicas. Sequence numbers are assigned to each operation before being forwarded to the replicas. While this approach works in ideal conditions — no server restarts, network downtime, hardware failures, or software upgrades — it relies on perfect circumstances.</p><p>In the real world, when assumptions like uptime or no failures are disrupted, Elasticsearch can enter a “failure” and “recovery” mode. If a primary shard fails, it may need to step down, and a replica takes its place. However, ongoing indexing operations might not be fully replicated, especially across multiple replicas, leading to discrepancies. Even with a single replica, if an old primary returns, it might contain operations not replicated to the new primary, causing potential issues.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*zfQynfPNeQZyDl5l3D5CzQ.png" /></figure><h3>Primary Terms &amp; Sequence Numbers</h3><p>To ensure consistency in Elasticsearch, primary terms are introduced to distinguish operations from older vs. newer primary shards. Primary terms increment each time a primary shard is promoted, representing the “generation” of the primary. This helps resolve conflicts between operations by giving precedence to newer terms over older ones, preventing issues from old operations.</p><p>In addition to primary terms, sequence numbers are used to track the exact order of indexing operations. This allows Elasticsearch to maintain the correct sequence of operations and resolve any discrepancies when a primary shard fails or is replaced.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*gegsiFUyedKxnkM9vg6oHw.png" /></figure><p>When Elasticsearch recovers from a primary shard failure, <strong>primary terms</strong> and <strong>sequence numbers</strong> help determine which operations to apply. However, this process can be expensive for large indices because of the high volume of operations, the need to track and compare many sequence numbers, and the time required for replica synchronization. The larger the index, the more resources are needed to ensure consistency and recovery. Elasticsearch uses local and global checkpoints to speed up this process.</p><h3>Global &amp; Local Checkpoints</h3><p>To overcome the computational cost of comparing large amounts of data and to accelerate recovery, Elasticsearch uses <strong>local</strong> and <strong>global</strong> checkpoints. The global checkpoint is a sequence number that indicates the highest point of consistency across all active shards. It represents the point up to which all active shards have processed operations. When a primary shard fails and is replaced, Elasticsearch only needs to compare operations above the global checkpoint. This reduces the need to compare the entire operation history, focusing only on operations that may not have been fully replicated.</p><p>Each shard also maintains a local checkpoint, which tracks the highest sequence number processed locally on that shard. Once all replicas of a primary shard acknowledge a write, the primary updates the global checkpoint and sends this information to all replicas. This allows Elasticsearch to quickly identify which operations need to be compared when recovering from a failure and ensures that only the necessary data is reprocessed. By utilizing local and global checkpoints, Elasticsearch significantly reduces the overhead associated with consistency checks, improving performance during recovery and minimizing the impact of shard failures.</p><p><strong>Thank you for reading until the end.</strong></p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=22d47ad33f25" width="1" height="1" alt=""><hr><p><a href="https://medium.com/dogus-tech-digital-solutions/how-does-elasticsearch-ensure-consistency-when-writing-data-22d47ad33f25">How does Elasticsearch ensure consistency when writing data?</a> was originally published in <a href="https://medium.com/dogus-tech-digital-solutions">Doğuş Technology</a> on Medium, where people are continuing the conversation by highlighting and responding to this story.</p>]]></content:encoded>
        </item>
    </channel>
</rss>