# Behavior

## Connect

`WebSocket.connect(url)` takes a `ws://` or `wss://` URL. The port defaults to 80 or 443 and the path to `/`. The fragment is dropped, and user info (`ws://user:pass@host`) is refused: send credentials in a header. An IPv6 host goes in brackets.

It opens a TCP connection (TLS for `wss`), sends the upgrade request with a new random `Sec-WebSocket-Key`, and checks the answer. The handshake is refused, and the socket closed, for a status other than 101, a missing `Upgrade: websocket` or `Connection: Upgrade`, a wrong `Sec-WebSocket-Accept`, a subprotocol that the client did not offer, and an extension (the client offers none).

`WebSocket.handshake(url)` does the same, but a server that answers with a status from 200 to 599 other than 101 is not an `error`: you get `Refused(status, headers, body)` and the socket is closed. Use it to see why a server said no (a 403 for a wrong `Origin`, a 426 for a wrong version, a 302). `Open(client)` is the same `Client` that `connect` returns, with the `status` (101) and the `headers` of the answer, in the names that the server wrote. `connect` stops at the head of a refusing answer and never reads its body.

The body of a refused answer follows these rules:

- It is read as long as the first `Content-Length` says, at most 64 KiB. A value of digits that does not fit an Int counts as 64 KiB; a value that is not a number, or no `Content-Length`, gives `""` (a chunked body is not read).
- The bytes that came before the peer closed or the deadline ended are kept, so a short or a stalled body gives what arrived.
- A body that is cut in the middle of a UTF-8 character (at the cap, or by the peer) loses that last character. If the bytes are still not UTF-8, the body is `""`.
- `timeout_ms` covers the sending of the request, the head and the body together, counted after the connect.

A status outside 200 to 599 other than 101 (a 1xx such as 100, 0, 600 and above) is an `error`: a 1xx answer is not skipped. A 3xx is a `Refused`. An `error` is also a bad URL or option, a failed connect, a timeout, an answer that is not HTTP, and a 101 that is not a good handshake:

```agentica
import WebSocket from "pkg/websocket-client/websocket"

def why(url: String) -> Result[Void]
  case try WebSocket.handshake(url)
    WebSocket.Handshake.Open(ws) -> puts("open, protocol #{ws.protocol}")
    WebSocket.Handshake.Refused(status, _, body) -> puts("refused #{status}: #{body}")
  end

  ok()
end
```

`Options.headers` go in the request: cookies, `Authorization`, `Origin`. `Host`, `Upgrade`, `Connection` and the `Sec-WebSocket-*` headers are written by the handshake and refused here, as is a name that is not a token or a value with a line break.

`Options.protocols` lists the subprotocols to offer, and `client.protocol` is the one the server chose (`""` for none):

```agentica
import WebSocket from "pkg/websocket-client/websocket"
import HTTP from "std/http"

def connect_to_cable() -> Result[WebSocket.Client]
  options = WebSocket.Options(
    protocols: ["actioncable-v1-json"],
    headers: [
      HTTP.Header(name: "Cookie", value: "user=ana"),
      HTTP.Header(name: "Origin", value: "http://127.0.0.1:3000"),
    ],
  )
  WebSocket.connect("ws://127.0.0.1:3000/cable", options)
end
```

For `wss`, the system trust is used. To trust another certificate, build a context and pass it as `tls`:

```agentica
import WebSocket from "pkg/websocket-client/websocket"

def connect_with_ca() -> Result[WebSocket.Client]
  context = try TLS.client_context(TLS.ClientOptions(ca_file: "ca.pem"))
  WebSocket.connect("wss://localhost:8443/", WebSocket.Options(tls: some(context)))
end
```

## Send

`send_text`, `send_binary`, `send_ping` and `send_pong` write one whole frame, always masked with a new random key. A ping or a pong carries at most 125 bytes. A message is at most 1 MiB less its frame head, because a frame goes out in one write, so that tasks that send at once never mix their frames; a larger payload is an `error` before anything is sent. A send that times out (`timeout_ms`) closes the socket.

Every timeout (`timeout_ms`, `read_timeout_ms`, `close_timeout_ms`) is from 1 to 86,400,000 milliseconds (one day). A larger value is an `error`, from `connect` and also from `receive` and `close`, so a value that stands for "never" cannot overflow a deadline; use one day.

Masking runs in Agentica, at about 2 MB/s.

## Receive

`receive` waits for the next message and returns it whole:

- Fragments of a message are joined, and a control frame between them is handled on the way.
- A ping is answered at once with a pong that has the same payload. A pong is dropped.
- A text message is checked to be UTF-8.
- A close frame is answered with its code, the socket is closed, and `receive` returns `Close(code, reason)`. The code is 1005 when the server sent none. A connection that ends with no close frame (the server dropped it, even in the middle of a frame, or reset it) is `Close(1006, "")`, as the server of `std/http` tells its sessions.
- After a `Close`, or after `close`, the next `receive` is an `error`.

These make `receive` close the connection with a close frame and return an `error` with the rule that was broken:

| What the server sent | Close code |
|---|---|
| a masked frame, a reserved bit (no extension is in use), an unknown opcode, a control frame over 125 bytes or fragmented, a continuation with no message, a new message inside a fragmented one, a length that is not in its shortest form, a bad close frame (one byte, or a code that no peer may send) | 1002 |
| a text message that is not UTF-8, or a close reason that is not | 1007 |
| a message over `max_message_bytes` (all its fragments together) | 1009 |

The size is checked from the head of a frame, before its payload is read, so a server cannot make the client hold more than `max_message_bytes`.

`read_timeout_ms` is the time for one whole frame, from the first byte to the last, so a server that sends a byte now and then cannot hold `receive`. A frame that is not complete by then is an `error` and the connection is closed. A server that pings keeps the connection alive, since each frame that arrives starts a new wait. The handshake and the wait of `close` have their own deadline the same way. For a quiet server, use a long `read_timeout_ms`.

## Close

`WebSocket.close(ws, 1000, "done")` sends a close frame, waits up to `close_timeout_ms` for the answer, drops the data that arrives meanwhile, and closes the socket. It returns `ok` also when the connection was already closed. The code is 1000 to 1003, 1007 to 1014, or 3000 to 4999, and the reason is at most 123 bytes: another one is an `error` and nothing is sent.

A socket also closes when the task that connected ends, so connect in the task that keeps the connection.

## Tasks

The functions can be called from any task, and a send and a receive can run at the same time. To read in the background, give the connection to a task that puts the messages in a channel. The task that connected must live as long as the connection:

```agentica
import WebSocket from "pkg/websocket-client/websocket"
import HTTP from "std/http"

struct Line
  ws: WebSocket.Client
  inbox: Channel[WebSocket.Message]
end

def count_up(ws: HTTP.WebSocket) -> Result[Void]
  for n in 1..3
    try ws.outgoing.send(HTTP.Message.Text("tick #{n}"), 5000)
  end

  ws.outgoing.send(HTTP.Message.Close(1000, "enough"), 5000)
end

def route(request: HTTP.Request, _body: HTTP.RequestBody) -> Result[HTTP.Answer]
  ok(HTTP.Answer.Upgrade(try HTTP.accept_websocket(request, &count_up)))
end

# The task that reads: it puts every message in the channel, and ends with the close.
def pump(line: Line) -> Void
  while true
    case WebSocket.receive(line.ws)
      ok(message) ->
        _ = line.inbox.send(message, 5000)
        case message
          WebSocket.Message.Close(_, _) -> break
          WebSocket.Message.Text(_) -> nil
          WebSocket.Message.Binary(_) -> nil
        end

      error(_) -> break
    end
  end

  line.inbox.close
end

def main() -> Void
  server = HTTP.serve("127.0.0.1", 0, &route).unwrap!
  ws = WebSocket.connect("ws://127.0.0.1:#{HTTP.local_port(server)}/").unwrap!
  inbox: Channel[WebSocket.Message] = Channel.new(8)
  reader = Task.spawn(&pump, Line(ws: ws, inbox: inbox))
  while true
    case inbox.recv(5000)
      error(_) -> break
      ok(message) ->
        case message
          WebSocket.Message.Text(text) -> puts(text)
          WebSocket.Message.Binary(_) -> nil
          WebSocket.Message.Close(code, reason) -> puts("closed #{code} #{reason}")
        end
    end
  end

  Task.await(reader)
  HTTP.close_server(server)
end
```

```output
tick 1
tick 2
tick 3
closed 1000 enough
```

## Not in this version

- permessage-deflate (compression): the client offers no extension, and refuses a server that chooses one.
- A message over 1 MiB to send, which would need to be fragmented.
- Redirects, proxies, and an automatic reconnect.
- A built-in receive task and channel.
