testing/cross_backend/ws_role_gated.ts

Cross-process role-gated WebSocket suite — a socket admitted by an endpoint's role gate (register_ws_endpoint's required_roles) loses it with the role.

A role gate decides who may hold a socket, and so who receives the endpoint's server pushes, which reach every admitted connection with no per-recipient filter. So both spines record the gating roles on each registration and close the account's gated sockets when a global grant of a listed role is revoked — with WS_CLOSE_PERMISSION_REVOKED, not the session-revoked code, since the credential is still good — and send nothing after the close. The ungated sockets of the same account, on the same transport, stay open: the gate is per endpoint, not per account. A scoped grant never admits at a role gate, so revoking one closes nothing.

Runs against a backend that mounts, beside its ungated ws_path, a second endpoint at gated_ws_path gated on gated_roles — which must include ROLE_ADMIN (the revoked global grant) and a role that can be granted both globally and scoped (the scoped revoke). fuz_app's spine binaries mount SPINE_ROLE_GATED_WS_PATH gated on SPINE_ROLE_GATED_WS_ROLES. Gated on capabilities.ws and capabilities.ws_role_gated; cross-process only.

view source

Declarations
#

2 declarations

describe_ws_role_gated_cross_tests
#

testing/cross_backend/ws_role_gated.ts view source

(options: WsRoleGatedCrossTestOptions): void import {describe_ws_role_gated_cross_tests} from '@fuzdev/fuz_app/testing/cross_backend/ws_role_gated.js';

Register the role-gated WebSocket suite: a revoked global grant of a gating role closes the account's gated socket with WS_CLOSE_PERMISSION_REVOKED, its ungated socket stays open and still receives the account's pushes, and a re-upgrade is refused at the gate; a scoped revoke of a gating role closes nothing.

That the closed registration is sent nothing more is beyond what a client can observe once it has read the close frame, so the suite does not claim it: each spine's own transport tests pin it.

options

returns

void

WsRoleGatedCrossTestOptions
#

testing/cross_backend/ws_role_gated.ts view source

WsRoleGatedCrossTestOptions import type {WsRoleGatedCrossTestOptions} from '@fuzdev/fuz_app/testing/cross_backend/ws_role_gated.js';

setup_test

Per-test fixture producer (default_cross_process_setup(handle)).

type (): Promise<TestFixtureBase>

readonly
returns Promise<TestFixtureBase>

capabilities

Backend capability flags; every case gates on ws and ws_role_gated.

type BackendCapabilities

readonly

base_url

Base URL the backend is reachable at.

type string

readonly

ws_path

The ungated WebSocket endpoint path (e.g. /api/ws).

type string

readonly

gated_ws_path

The role-gated WebSocket endpoint path.

type string

readonly

gated_roles

The roles gated_ws_path requires: ROLE_ADMIN and scoped_role among them.

type readonly string[]

readonly

scoped_role

A role in gated_roles an admin can grant both globally and scoped.

type string

readonly

rpc_path?

JSON-RPC endpoint path. Default SPINE_RPC_PATH.

type string

readonly

Depends on
#