
# All properties

Every property `spring_boot_starter_websocket` reads: the clients' settings, per client under `spring.websocket.client.config.<name>.*` (or `default`), and two message size limits for all clients. The server endpoints' limits are the web starter's `server.websocket.*` keys, listed at the end. The starter's metadata (`lib/spring_gen/spring_metadata.json`) lists the same 11 client keys.

## Why

How quickly a client reconnects, how long it waits for a handshake and how large a message may be depend on the network and the server, which differ between environments. Properties change them without a build.

## Example

```yaml
# lib/resources/application.yml
chat:
  url: wss://chat.neon.books/ws

spring:
  websocket:
    client:
      max-text-message-size: 1MB
      max-binary-message-size: -1
      config:
        default:
          connect-timeout: 5s
          reconnect:
            delay: 1s
            multiplier: 2
            max-delay: 30s
        chat:
          url: ${chat.url}
          reconnect:
            delay: 500ms
            jitter: 100ms
            max-retries: 10
        feed:
          default-request-headers:
            X-Api-Key: ${FEED_KEY}
          reconnect:
            enabled: false
```

The same in `.properties`:

```properties
# lib/resources/application.properties
chat.url=wss://chat.neon.books/ws
spring.websocket.client.max-text-message-size=1MB
spring.websocket.client.max-binary-message-size=-1
spring.websocket.client.config.default.connect-timeout=5s
spring.websocket.client.config.default.reconnect.delay=1s
spring.websocket.client.config.default.reconnect.multiplier=2
spring.websocket.client.config.default.reconnect.max-delay=30s
spring.websocket.client.config.chat.url=${chat.url}
spring.websocket.client.config.chat.reconnect.delay=500ms
spring.websocket.client.config.chat.reconnect.jitter=100ms
spring.websocket.client.config.chat.reconnect.max-retries=10
spring.websocket.client.config.feed.default-request-headers.X-Api-Key=${FEED_KEY}
spring.websocket.client.config.feed.reconnect.enabled=false
```

## Per client: spring.websocket.client.config

Each key is `spring.websocket.client.config.<name>.<key>`; what a client does not set falls back to `default`.

| Key | Type | Default | Meaning |
|---|---|---|---|
| `url` | `String` | none | The address, when `@WebSocketClient(url:)` is not set; `ws://` or `wss://`. `${...}` placeholders are allowed. |
| `connect-timeout` | `Duration` | `10s` | The longest a handshake may take. |
| `default-request-headers.<Name>` | `List<String>` | none | Headers sent with the handshake, such as an API key (a comma list or an indexed list gives several values); not possible in browsers. A client's header replaces the `default` one of the same name. |
| `reconnect.enabled` | `bool` | `true` | Reconnects while someone listens to the messages. With `false`, a lost connection ends the message streams. Takes `true` / `false`, `on` / `off`, `yes` / `no`, `1` / `0`. |
| `reconnect.delay` | `Duration` | `1s` | The first wait; not negative. |
| `reconnect.multiplier` | `double` | `2` | What each further wait is multiplied by; `1` for a fixed delay, not less. |
| `reconnect.max-delay` | `Duration` | `30s` | The longest wait; positive. Also how long a connection must stay open to count as stable. |
| `reconnect.jitter` | `Duration` | none | A random part added or taken, scaled like the delay; not negative. |
| `reconnect.max-retries` | `int` | no limit | Attempts in a row before giving up; not negative. |
| `max-text-message-size` | `DataSize` | `spring.websocket.client.max-text-message-size` | The largest text message this client reads, in UTF-8 bytes; a larger one closes the connection with 1009. `-1` for no limit. |
| `max-binary-message-size` | `DataSize` | `spring.websocket.client.max-binary-message-size` | The same for binary messages. |
| `phoenix.heartbeat-interval` | `Duration` | `30s` | For a [Phoenix Channels client](phoenix.md): the time between two heartbeats; `0` sends none. |
| `phoenix.push-timeout` | `Duration` | `10s` | The longest a join, a push or a leave of a Phoenix channel waits for its reply. |
| `phoenix.vsn` | `String` | `2.0.0` | The version of the Phoenix wire format: `2.0.0` or `1.0.0`. `@PhoenixChannel(vsn:)` wins. |

A wrong value fails the start, naming the property.

## For all clients: spring.websocket.client

| Key | Type | Default | Meaning |
|---|---|---|---|
| `spring.websocket.client.max-text-message-size` | `DataSize` | `8KB` | The largest text message a client reads, in UTF-8 bytes (Tomcat counts characters); a larger one closes the connection with 1009 (message too big). `-1` for no limit. |
| `spring.websocket.client.max-binary-message-size` | `DataSize` | `8KB` | The same for binary messages. `-1` for no limit. |

They hold for every client that sets no limit of its own under `config.<name>` or `config.default`. The browser transport has no limit.

## Writing values

- **Durations:** `500ms`, `5s`, `1m`, ISO 8601 (`PT5S`) or milliseconds. See [Durations](../spring-core-dart/conversion/durations.md).
- **Data sizes:** `512B`, `8KB`, `1MB`, or bytes; `-1` for no limit. See [Data sizes](../spring-core-dart/conversion/data-size.md).

## Server endpoints: server.websocket (web starter)

The limits of the server's sessions belong to [spring_boot_starter_web](../spring-boot-starter-web/properties.md):

| Key | Type | Default | Meaning |
|---|---|---|---|
| `server.websocket.max-text-message-size` | `DataSize`, or `-1` | `8KB` | The largest text message a session reads, in UTF-8 bytes; a larger one closes the session with 1009. |
| `server.websocket.max-binary-message-size` | `DataSize`, or `-1` | `8KB` | The same for binary messages. |
| `server.websocket.send-buffer-size-limit` | `DataSize`, or `-1` | `512KB` | How much may wait to be sent to a slow client; past it the connection is dropped with 4500. |
| `server.websocket.send-time-limit` | `Duration`, or `-1` | `10s` | How long what was sent may take to leave; past it the connection is dropped with 4500. |

## In Spring (Java)

Spring has no WebSocket client properties: `spring.websocket.client.*` is this project's own. The `reconnect.*` names follow Spring 7's `RetryPolicy`. Spring sets message limits in code (`WebSocketContainer`, `ServletServerContainerFactoryBean`).

## See also

- [Client configuration](client-configuration.md)
- [Phoenix Channels client](phoenix.md)
- [Server endpoints](server-endpoints.md)
- [WebSocket in the web starter](../spring-boot-starter-web/server/websocket.md)
