Bgp4Server

Bgp4Server is the peer for Bgp4Client. It unwraps upstream BGP-like frames from the client side and wraps downstream payloads in the reverse direction.

It is intended to be paired with Bgp4Client:

TcpListener -> Bgp4Client -> ... -> Bgp4Server -> TcpConnector

warning

Bgp4Server does not implement real BGP routing, BGP peering, route exchange, or BGP authentication. It only understands the BGP-like framing produced by Bgp4Client.

What It Does

• Initializes one per-line read stream and first-frame state during upstream init.
• Requires the first upstream frame to be a synthetic OPEN frame from Bgp4Client.
• Strips the first frame's BGP metadata and synthetic OPEN body.
• Strips marker, length, and type from later upstream frames.
• Forwards recovered upstream payloads to the next tunnel.
• Wraps downstream payloads as BGP-like frames before sending them to the previous tunnel.
• Closes both directions when it receives malformed framed data.

Bgp4Server is a normal stream tunnel. It does not create network sockets and does not create or destroy packet lines.

Configuration Example

Server side:

{
  "name": "bgp4-server",
  "type": "Bgp4Server",
  "settings": {
    "password": "compat-value"
  },
  "next": "target"
}

Paired client side:

{
  "name": "bgp4-client",
  "type": "Bgp4Client",
  "settings": {
    "password": "compat-value"
  },
  "next": "transport-out"
}

The password field is accepted for compatibility with the old configuration shape, but it is not used for encryption or authentication in the current protocol logic.

Required Fields

Top-level fields:

Field	Type	Description
name	string	User-chosen node name. Must be unique inside the config file.
type	string	Must be exactly "Bgp4Server".
next	string	The next stream node that receives unwrapped upstream payloads.

Optional Settings

Setting	Type	Default	Description
password	string	"passwd"	Compatibility field. It is hashed during setup but the hash is not used by current framing logic.

No other settings are currently parsed.

Frame Format

Bgp4Server reads and writes the same BGP-like frame shape as Bgp4Client:

16-byte marker | 2-byte body length | 1-byte BGP type | body

Field details:

Field	Value
marker	Sixteen bytes of 0xff.
body length	Big-endian uint16_t. Covers the type byte plus body bytes.
BGP type	First upstream frame must be 1; downstream frames use random 2 through 5.
body	Tunneled payload, or synthetic OPEN body plus tunneled payload for the first upstream frame.

Supported type values used by the implementation:

Type	Name
1	OPEN
2	UPDATE
3	NOTIFICATION
4	KEEPALIVE
5	ROUTE-REFRESH

The length field is the WaterWall BGP-like tunnel length, not the standard BGP message length: it covers the type byte plus body bytes, excluding the marker and length field.

First Upstream Frame

The first upstream frame must be type 1 and must contain a synthetic OPEN body followed by tunneled payload bytes.

For the first frame, Bgp4Server:

1. Verifies the frame has at least the 1-byte type plus 10-byte OPEN header.
2. Verifies that the type is OPEN.
3. Reads the optional parameter length from the OPEN header.
4. Calculates the full synthetic OPEN prefix length.
5. Rejects the frame if no tunneled payload remains after the OPEN prefix.
6. Marks the line as having received OPEN.
7. Strips the type and OPEN prefix.
8. Forwards the remaining payload upstream.

Later upstream frames only strip the 1-byte type. The recovered body must not be empty.

Downstream Wrapping

Downstream payloads are wrapped before being sent toward the previous tunnel.

Bgp4Server uses a random non-OPEN BGP type for downstream payload frames:

2, 3, 4, or 5

The payload is not encrypted or authenticated by this node. It is only framed.

Limits

Limit	Value	Notes
Maximum body length	65535 bytes	Includes the 1-byte type.
Maximum ordinary payload body	65534 bytes	Payload plus type must fit in 65535.
Maximum buffered read bytes	about 131106 bytes	Two maximum-size framed messages.
Required left padding	19 bytes	Frame marker, length, and type.

If a downstream payload cannot fit into one BGP-like frame, it is refused and no wrapped frame is forwarded.

Data Flow

Upstream direction:

previous node -> Bgp4Server unwraps -> next node

Downstream direction:

next node -> Bgp4Server wraps -> previous node

The upstream side must receive frames produced by Bgp4Client. If the first upstream frame is not the expected synthetic OPEN frame, the line is closed.

Lifecycle Behavior

On upstream init, Bgp4Server initializes its line state and forwards upstream init to the next tunnel.

On downstream est, it forwards downstream est to the previous tunnel.

On upstream payload, it buffers, parses, validates, unwraps, and forwards recovered payloads to the next tunnel. On downstream payload, it wraps and forwards to the previous tunnel.

On upstream finish, it destroys its own line state and forwards upstream finish to the next tunnel. On downstream finish, it destroys its own line state and forwards downstream finish to the previous tunnel.

On malformed framed data, Bgp4Server destroys local state and closes both directions in middle-tunnel order: upstream finish first, then downstream finish.

Pause and resume are forwarded directionally:

Callback	Forwarded to
upstream pause/resume	next tunnel upstream
downstream pause/resume	previous tunnel downstream

Notes and Caveats

• Bgp4Server requires a paired Bgp4Client for useful operation.
• password is not a security feature in the current implementation.
• The first upstream frame must be an OPEN frame with tunneled payload after the synthetic OPEN body.
• The BGP-like length field excludes the marker and length bytes.
• Upstream est and downstream init are disabled callbacks.
• This node is a layer-4 stream tunnel, not a packet tunnel.