user_timeout

user_timeout is implemented by handleUserTimeout in src/api/handlers/user/user_timeout.osl.

Persists a timeout in seconds. The current handler broadcasts the millisecond rate_limit frame to every authenticated connection except the actor, then sends it directly to the target again, so the target can receive it twice.

Access

Gate	Requirement
Authentication	Required by the central API gate.
Central permission	`manage_users`
Broadcast	Not marked global directly by this adapter. A helper may emit focused or server-wide updates.

Request

Every request includes cmd: "user_timeout" and may include an opaque listener correlation value.

Field	Validation / meaning
`user`	`schema.string().trim().minLen(1)`
`duration`	`schema.number().gt(0)`
`reason`	`schema.string().defaultValue("No reason provided")`

Validator source

The handler and shared validation path use these OSL schema definitions before normalization:

*schema.Schema schemaUserTimeout = schema.object({
  user: schema.string().trim().minLen(1),
  duration: schema.number().gt(0),
  reason: schema.string().defaultValue("No reason provided")
})

Processing path

handleCmd enforces authentication and the manage_users permission.
dispatchCmd routes user_timeout to handleUserTimeout.
The adapter validates and normalizes input, then calls its domain collaborators.
Durable mutations complete before the response or event is returned.
onMessage adds the request listener to direct responses and performs any marked broadcast.

Direct collaborators visible in the handler: userFromUsername, userFromId, userHasPermission, userTimeoutSet, broadcastAuthed, sendUser, auditRecord

Responses and events

Response/event command names visible in this adapter: rate_limit, user_timeout.

Validation and domain failures use:

{
  "cmd": "error",
  "val": "<message>",
  "src": "user_timeout",
  "listener": "<copied from request>"
}