Jon Staab
73 lines
2.1 KiB
Markdown
73 lines
2.1 KiB
Markdown
# Policy
|
|
|
|
Socket policies provide automated behavior for socket connections. They are intended to be applied on socket creation via `makeSocket` or `PoolOptions.makeSocket`.
|
|
|
|
## Types
|
|
|
|
### SocketPolicy
|
|
```typescript
|
|
type SocketPolicy = (socket: Socket) => Unsubscriber
|
|
```
|
|
|
|
The contract for socket policies. Takes a Socket object and returns a cleanup function that should be called when the policy is no longer needed.
|
|
|
|
## Built-in Policies
|
|
|
|
### `socketPolicyPing`
|
|
|
|
Sends a PING message every 30 seconds when the socket is open and has been idle (no send or receive activity in the last 30 seconds). Keeps connections alive through NAT/firewall idle timeouts.
|
|
|
|
### `socketPolicyAuthBuffer`
|
|
|
|
Buffers messages during authentication flow and replays them after successful auth.
|
|
|
|
### `socketPolicyConnectOnSend`
|
|
|
|
Auto-connects closed sockets when messages are sent (with error cooldown).
|
|
|
|
### `socketPolicyCloseInactive`
|
|
|
|
Closes sockets after 30 seconds of inactivity and reopens sockets that have pending requests or publishes.
|
|
|
|
## Custom Auth Policy
|
|
|
|
### `makeSocketPolicyAuth(options)`
|
|
|
|
Creates a policy that handles authentication challenges.
|
|
|
|
**Options:**
|
|
- `sign: (event) => Promise<SignedEvent>` - Signing function
|
|
- `shouldAuth?: (socket) => boolean` - Optional auth condition
|
|
|
|
## Default Policies
|
|
|
|
`defaultSocketPolicies` includes all built-in policies except auth (which requires configuration).
|
|
|
|
It's common to include the following code in order to enable automatic authentication on all connections:
|
|
|
|
```typescript
|
|
defaultSocketPolicies.push(
|
|
makeSocketPolicyAuth({
|
|
sign: (event: StampedEvent) => signer.sign(event),
|
|
shouldAuth: (socket: Socket) => true,
|
|
}),
|
|
)
|
|
```
|
|
|
|
## Example
|
|
|
|
It's possible to create custom policies simply by defining a function which returns a cleanup function:
|
|
|
|
```typescript
|
|
import {on} from "@welshman/lib"
|
|
import {SocketEvent, Socket, SocketStatus} from "@welshman/net"
|
|
|
|
const logStatusChangePolicy = (socket: Socket) => {
|
|
const unsubscribe = on(socket, SocketEvent.Status, (newStatus: SocketStatus) => {
|
|
console.log(socket.url, newStatus)
|
|
})
|
|
|
|
return unsubscribe
|
|
}
|
|
```
|