docs/app/extensions/websockets/page.mdx

export const metadata = {
    title: 'WebSocket Extension',
    description:
        'The WebSocket extension adds support for real-time communication between instances.',
}

# WebSockets Extension

<Note>
    This document is **provided for informative purposes** and should not be used in a production environment. It is subject to change.

    If internal testing proves unsuccessful at solving the problems with the HTTP delivery method, this document may be abandoned.
</Note>

Typically, communication between Versia instances is done via HTTP. However, HTTP suffers from some limitations, such as high latency and heavy overhead for small messages, making it less suitable for exchanging large amounts of entities at acceptable speeds. {{ className: 'lead' }}

This extension aims to address these limitations by adding support for the exchange of entities using WebSockets.

## Message Format

Messages sent over the WebSocket connection are JSON objects.

<Row>
    <Col>
        <Properties name="WebSocketMessage">
            <Property name="signature" type="string" required={true}>
                Same as the `Versia-Signature` header in HTTP requests.
            </Property>
            <Property name="signed_at" type="string" required={true}>
                Same as the `Versia-Signed-At` header in HTTP requests.
            </Property>
            <Property name="signed_by" type="URI" required={true}>
                Same as the `Versia-Signed-By` header in HTTP requests.
            </Property>
            <Property name="entity" type="Entity" required={true} typeLink="/entities">
                Same as the request body in HTTP requests. Must be a string (stringified JSON), not JSON.
            </Property>
        </Properties>
    </Col>

    <Col sticky>

    ```jsonc {{ 'title': 'Example Message' }}
    {
        "signature": "/CjB2L9bcvRg+uP19B4/rqy7Ji9/cqMFPlL3GVCIndnQjYyOpBzJEAl9weDnXm7Jrqa3y6sBC+EYWKThO2r9Bw==",
        "signed_at": "1729241807",
        "signed_by": "https://bongo.social/users/63a00ab3-39b1-49eb-b88e-ed65d2361f3e",
        "entity": "{\"id\":\"9a8928b6-2526-4979-aab1-ef2f88cd5700\",\"type\":\"Delete\",\"created_at\":\"2022-01-01T12:00:00Z\",\"author\":\"https://bongo.social/users/63a00ab3-39b1-49eb-b88e-ed65d2361f3e\",\"deleted\":\"https://bongo.social/notes/54059ce2-9332-46fa-bf6a-598b5493b81b\"}"
    }
    ```

    </Col>
</Row>

## Connection Establishment

...