welshman/docs/net/policy.md

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

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:

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:

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
}