# tcp

> The tcp identity: raw bytes over a TCP connection. Every directive and what is required.

`tcp` speaks raw bytes over a TCP connection. The session persists across steps, so a solution can stage an exchange in one step and continue it in the next. The target is `host:port`. Send and receive raw bytes as hex; a send may also be written as readable text with `send hex of "<text>"`.

## Write it in English

A tcp step reads as sentences: `send hex "<hex>"` sends bytes, `receive <n> bytes` reads at most that many, `receive until "<hex>"` stops at a marker, `port <n>` reconnects to another port, `timeout <n> seconds` bounds the wait, `close the connection` ends the session, and `expect ...` checks the hex response:

```text
tcp negotiate
  send hex "010203..."
  receive 4096 bytes
  timeout 5 seconds
  expect "..." in the response
```

`send hex of "<text>"` hex-encodes readable text with the usual escapes.

## The directives

### send

`send hex "<hex>"` is the bytes to send, written as hex, or `send hex of "<text>"` for readable text: the quoted text, with the `\r`, `\n`, `\t`, `\"`, `\\`, and `\xHH` escapes, is hex-encoded for you, so `send hex of "HELO x\r\n"` is the same bytes as `48454c4f20780d0a`. It may be omitted when a step only reads, for example a banner grab.

### receive

`receive <n> bytes` reads at most that many.

### receive until

`receive until "<hex>"` stops the read once this hex marker appears.

### timeout

`timeout <n> seconds` bounds the wait. Example: `timeout 5 seconds`.

### close

`close the connection` ends the session after this step.

### capture

`capture` pulls a value out of the received hex for later steps, and it reads as English. The `value after` shape captures the run of hex after a hex marker and hex-decodes it, the way a server-assigned port id rides in the stream:

```text
tcp negotiate
  send hex "010203..."
  capture the value after "6f703a6f747270633a" as port_id
  expect "..." in the response
```

Later steps reference `{port_id}`. The regex form is still available: the pattern runs over the hex and group 1 is hex-decoded before storing (`capture port: "(....)"`).

## Example

```text
tcp banner
  # read the service banner
  receive 4096 bytes
  timeout 5 seconds
  expect the response to match "..."
```

The step sends nothing; it only reads, so there is no `send hex` line.