Segments & Overflow

The problem

Sometimes one group key receives events faster than they can be delivered, for example during a traffic spike or while your endpoint is failing and deliveries are being retried. Rejecting or slowing down ingest is not an option: senders expect a fast response and may drop events or disable your endpoint. Webbu handles this with segments.

How it works

Each buffer has overflow limits:

{
  "overflow": {
    "maxGroupItems": 2000,
    "maxGroupBytes": 5242880,
    "policy": "flush_early_then_continue"
  }
}

When adding an item would take the current segment of a group past maxGroupItems items or maxGroupBytes bytes (5 MB by default), Webbu:

1. Schedules an immediate delivery of the current segment
2. Opens a new segment for the same group key
3. Stores the new item, and the ones that follow, in the new segment

Ingest is never blocked: the request still gets 202. flush_early_then_continue is currently the only policy.

Segments vs. maxItems

The overflow limits are a safety valve and are normally much larger than batch.maxItems. In regular operation a group is delivered when it reaches maxItems (or another flush condition), long before it reaches maxGroupItems, and stays in segment 0. A new segment appears only when items pile up, typically while deliveries for that key are failing or being retried.

Identifying segments

Every segment has its own group ID and is delivered independently:

groupId = {bufferId}:{groupHash}:{segment}

b_orders:9a1c0b7e3d5f2a48:0   ← first segment
b_orders:9a1c0b7e3d5f2a48:1   ← created on overflow

The delivery body includes webbu.segment.

Guarantees

• Ingest is not blocked by a large group
• Items within a delivery are in the order they were received
• Segments are delivered independently, so batches for the same key can arrive out of order relative to each other. Use items[].receivedAt if order matters