Add community node socket: devices, tickets, consent gate, kill switch

Phase 3 of plan.md. Device registration with one-time secrets, scoped single-use
socket tickets, the lock-owner WS /nodes/ws with handshake and heartbeat eviction,
a single batch ConsentGate, and NodesService which disconnects nodes within one tick
when consent, device or the nodes_enabled kill switch changes. A reconcile of 2000
sessions measured about 110 ms after replacing per-session queries with batches.
Devii may withdraw but never grant bandwidth_sharing.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
This commit is contained in:
2026-10-14 09:14:53 +02:00
co-authored by Claude Sonnet 5.5
parent fad41d0fbe
commit 42b81271b8
41 changed files with 2166 additions and 22 deletions
+4
View File
@@ -43,6 +43,7 @@ from .moderation import (
CONSENTS_TABLE,
CONSENT_KINDS,
CONSENT_STATES,
MEMBER_ONLY_CONSENTS,
MATURITY_LEVELS,
MATURITY_SOURCES,
MATURITY_TABLE,
@@ -62,6 +63,7 @@ from .moderation import (
band_allows_mature,
band_allows_restricted,
consent_granted,
consent_granted_many,
consent_state,
get_maturity,
get_maturity_by_targets,
@@ -261,6 +263,7 @@ __all__ = [
"AGE_BANDS",
"CONSENTS_TABLE",
"CONSENT_KINDS",
"MEMBER_ONLY_CONSENTS",
"CONSENT_STATES",
"MATURITY_LEVELS",
"MATURITY_SOURCES",
@@ -281,6 +284,7 @@ __all__ = [
"band_allows_mature",
"band_allows_restricted",
"consent_granted",
"consent_granted_many",
"consent_state",
"get_maturity",
"get_maturity_by_targets",
+18
View File
@@ -144,6 +144,7 @@ CONSENT_KINDS: dict[str, str] = {
),
}
CONSENT_STATES: tuple[str, ...] = ("granted", "withdrawn")
MEMBER_ONLY_CONSENTS: frozenset[str] = frozenset({"bandwidth_sharing"})
AGE_BANDS: tuple[str, ...] = ("under_min", "13_15", "16_17", "adult")
@@ -300,6 +301,23 @@ def consent_granted(owner_kind: str, owner_id: str, kind: str) -> bool:
return bool(row and row.get("state") == "granted")
def consent_granted_many(owner_kind: str, owner_ids, kind: str) -> set[str]:
unique = list(dict.fromkeys(owner_id for owner_id in owner_ids if owner_id))
latest: dict[str, str] = {}
for start in range(0, len(unique), 500):
placeholders, params = _in_clause(unique[start : start + 500])
for row in db.query(
f"SELECT owner_id, state FROM {CONSENTS_TABLE} WHERE owner_kind = :owner_kind "
f"AND kind = :kind AND deleted_at IS NULL AND owner_id IN ({placeholders}) "
"ORDER BY created_at, id",
owner_kind=owner_kind,
kind=kind,
**params,
):
latest[row["owner_id"]] = row["state"]
return {owner_id for owner_id, state in latest.items() if state == "granted"}
def set_consent(
owner_kind: str, owner_id: str, kind: str, granted: bool, version: str = "1"
) -> dict | None:
+33 -1
View File
@@ -12,7 +12,7 @@ from sqlalchemy import text
from devplacepy.config import SECRET_KEY
from devplacepy.services.nodes.spec import DEVICE_KINDS, SPEC
from .core import _now_iso, db, get_table
from .core import _in_clause, _now_iso, db, get_table
from .soft_delete import soft_delete
LIMITS = SPEC.limits
@@ -23,6 +23,7 @@ SECRET_BYTES = 32
LABEL_MAX = 60
EVENT_DETAIL_MAX = 500
MEGABYTE = 1024 * 1024
BATCH_SIZE = 500
HOURS_PATTERN = re.compile(r"^([01]\d|2[0-3]):[0-5]\d$")
PLATFORMS = tuple(sorted({item.adapter for item in SPEC.destinations}))
FLAG_OPEN = "open"
@@ -125,6 +126,37 @@ def get_device(device_uid: str) -> dict | None:
return get_table("node_devices").find_one(uid=device_uid, deleted_at=None)
def _batches(values) -> list[list[str]]:
unique = list(dict.fromkeys(value for value in values if value))
return [unique[i : i + BATCH_SIZE] for i in range(0, len(unique), BATCH_SIZE)]
def get_devices_by_uids(device_uids) -> dict[str, dict]:
found: dict[str, dict] = {}
for batch in _batches(device_uids):
placeholders, params = _in_clause(batch)
for row in db.query(
f"SELECT * FROM node_devices WHERE uid IN ({placeholders}) "
"AND deleted_at IS NULL",
**params,
):
found[row["uid"]] = dict(row)
return found
def get_enabled_by_users(user_uids) -> dict[str, bool]:
found: dict[str, bool] = {}
for batch in _batches(user_uids):
placeholders, params = _in_clause(batch)
for row in db.query(
f"SELECT user_uid, enabled FROM node_settings WHERE user_uid IN ({placeholders}) "
"AND deleted_at IS NULL",
**params,
):
found[row["user_uid"]] = bool(row["enabled"])
return found
def list_devices(user_uid: str) -> list[dict]:
return list(
get_table("node_devices").find(
+2
View File
@@ -498,6 +498,8 @@ def init_db():
("uid", ""),
("token", ""),
("user_uid", ""),
("scope", ""),
("device_uid", ""),
("created_at", ""),
("expires_at", ""),
("used_at", ""),
+90 -1
View File
@@ -1,6 +1,20 @@
# retoor <retoor@molodetz.nl>
from .._shared import endpoint
from .._shared import endpoint, field
DEVICE_SAMPLE = {
"uid": "DEVICE_UID",
"label": "Home laptop",
"kind": "native",
"platform": "linux/amd64",
"client_version": "0.1.0",
"status": "active",
"suspended_until": None,
"country": "NL",
"asn_class": "residential",
"last_seen_at": "2026-01-01T00:00:00+00:00",
"created_at": "2026-01-01T00:00:00+00:00",
}
GROUP = {
"slug": "nodes",
@@ -65,5 +79,80 @@ page. Every endpoint follows the shared [Conventions & Errors](/docs/conventions
"Clients and the server read the same numbers from here; a contract test fails when they drift.",
],
),
endpoint(
id="nodes-devices-list",
method="GET",
path="/nodes/devices",
title="List your devices",
summary="The devices you registered, with their status and when they last connected. Secrets are never listed.",
auth="user",
interactive=True,
sample_response={"devices": [DEVICE_SAMPLE], "max_devices": 5},
),
endpoint(
id="nodes-devices-create",
method="POST",
path="/nodes/devices",
title="Register a device",
summary="Register one client install. The device secret is returned once and cannot be read again.",
auth="user",
ajax=True,
encoding="form",
params=[
field("label", "form", "string", False, "Home laptop", "A name only you see, up to 60 characters."),
field("kind", "form", "string", False, "native", "`native`, `extension` or `container`.", options=["native", "extension", "container"]),
field("platform", "form", "string", False, "linux/amd64", "Operating system and architecture of the client."),
field("client_version", "form", "string", False, "0.1.0", "Version of the client."),
],
sample_response={"device": DEVICE_SAMPLE, "secret": "dpn_EXAMPLE_SECRET_SHOWN_ONCE"},
notes=[
"Refused with `403` and a `reason` (`kill_switch`, `no_consent`, `not_enabled`, `not_adult`, `deletion_pending`, `suspended`, `account_inactive`) unless donation is switched on, you are an adult, you have given the `bandwidth_sharing` consent and enabled donation for yourself.",
"Refused with `409` when you already have the maximum number of devices.",
"The response is `201` and is never cached.",
],
),
endpoint(
id="nodes-devices-rotate",
method="POST",
path="/nodes/devices/{device_uid}/rotate",
title="Rotate a device secret",
summary="Issue a new secret for one of your devices. The old secret stops working immediately.",
auth="user",
ajax=True,
params=[
field("device_uid", "path", "string", True, "DEVICE_UID", "Device uid."),
],
sample_response={"uid": "DEVICE_UID", "secret": "dpn_EXAMPLE_SECRET_SHOWN_ONCE"},
notes=["`404` for a device that is not yours."],
),
endpoint(
id="nodes-devices-delete",
method="POST",
path="/nodes/devices/{device_uid}/delete",
title="Delete a device",
summary="Remove a device. A connected node is disconnected on the next service tick. An administrator may remove any device.",
auth="user",
ajax=True,
destructive=True,
params=[
field("device_uid", "path", "string", True, "DEVICE_UID", "Device uid."),
],
sample_response={"ok": True},
),
endpoint(
id="nodes-ticket",
method="POST",
path="/nodes/ticket",
title="Exchange a device secret for a socket ticket",
summary="The node client calls this with its device secret to get a single-use ticket for `WS /nodes/ws?ticket=`.",
auth="user",
interactive=False,
sample_response={"ticket": "TICKET", "expires_in": 30, "ws_path": "/nodes/ws"},
notes=[
"Authenticated by `Authorization: Bearer dpn_...` with the device secret, not by a session. Anything else is `401`.",
"The ticket is valid for 30 seconds and can be redeemed once. The socket then speaks the frames published in the [protocol specification](/docs/nodes-protocol.html).",
"`403` with a `reason` when the device is suspended or its owner no longer passes the consent gate.",
],
),
],
}
+2
View File
@@ -128,6 +128,7 @@ from devplacepy.services.audit import AuditService
from devplacepy.services.moderation.service import ModerationService
from devplacepy.services.moderation.screening import ContentRefused
from devplacepy.services.acceptance.service import AcceptanceService
from devplacepy.services.nodes.service import NodesService
from devplacepy.services.audit import record as audit
from devplacepy.services.push import PushService
from devplacepy.services.telegram import TelegramService
@@ -297,6 +298,7 @@ async def lifespan(app: FastAPI):
service_manager.register(AuditService())
service_manager.register(ModerationService())
service_manager.register(AcceptanceService())
service_manager.register(NodesService())
service_manager.register(PushService())
service_manager.register(TelegramService())
service_manager.register(TelegramOutboxService())
+16
View File
@@ -1124,6 +1124,22 @@ class BanForm(BaseModel):
reason: str = Field(default="", max_length=200)
class NodeDeviceForm(BaseModel):
label: str = Field(default="", max_length=60)
kind: str = Field(default="native", max_length=20)
platform: str = Field(default="", max_length=40)
client_version: str = Field(default="", max_length=40)
@field_validator("kind")
@classmethod
def known_kind(cls, value):
from devplacepy.services.nodes.spec import DEVICE_KINDS
if value not in DEVICE_KINDS:
raise ValueError("Unknown device kind")
return value
class ConsentForm(BaseModel):
kind: str = Field(min_length=1, max_length=40)
granted: str = Field(default="0", max_length=5)
+1 -1
View File
@@ -53,7 +53,7 @@ Prefixes are wired in `main.py`:
| (none) | push.py - push + PWA: `GET /push.json` (VAPID public key + the providers accepting registrations; `apns` includes `environment` when active), `POST /push.json` (register with any active provider; a body without `provider` is a `webpush` body; an APNs body is `token` plus optional `client_id` for device-stable upsert; created/revived rows are probed and the JSON may include `delivered`/`error`; an unknown, disabled or unconfigured provider is a 400), `DELETE /push.json` (unregister exactly the one registration named by `endpoint`/`token`/`client_id`, same identity priority as registration; idempotent, always 200 `{unregistered}`; wired into `PushManager.js`'s logout-link interceptor so a webpush subscription is dropped before the browser navigates to `/auth/logout`), `GET /service-worker.js`, `GET /manifest.json`. Provider protocol and delivery live in `devplacepy/push/` - see `devplacepy/push/CLAUDE.md` |
| (none) | docs.py (docs/ package) - the documentation site (prose pages + API reference). See `routers/docs/CLAUDE.md` for the deep detail on this tree (`DOCS_PAGES`, audience tiers, prose rendering pipeline) |
| `/skills` | skills.py - per-user Agent Skills: `GET ""` (list), `GET /{name}` (detail), `POST /install` (fetch a `SKILL.md` from a URL, update in place), `POST /{name}/enabled`, `POST /{name}/delete` (owner, or an administrator naming `owner`). Private to the owner, `noindex`. See `devplacepy/services/skills/CLAUDE.md` |
| `/nodes` | nodes/ package - community node network. Today only `spec.py` (`GET /nodes/spec.json`, public, returns `SPEC.describe()`); the socket, device and consent routes are planned. See `devplacepy/services/nodes/CLAUDE.md` |
| `/nodes` | nodes/ package - community node network. `spec.py` (`GET /nodes/spec.json`, public, `SPEC.describe()`), `devices.py` (`GET/POST /nodes/devices`, `POST /nodes/devices/{uid}/rotate|delete`, `require_user_api`, secret returned once, `no-store`), `ticket.py` (`POST /nodes/ticket`, authenticated by `Authorization: Bearer dpn_...`, never a session), `ws.py` (`WS /nodes/ws?ticket=`, lock-owner gated, `4013` retry). Needs its own nginx upgrade block. See `devplacepy/services/nodes/CLAUDE.md` |
| `/pubsub` | pubsub.py - **database-free** publish/subscribe bus. `WS /pubsub/ws` (subscribe/unsubscribe/publish frames, `foo.*` wildcards), `POST /pubsub/publish` + `GET /pubsub/topics` (admin/internal). Lock-owner-gated WS (`4013` retry) so subscribers converge on one worker; topic authz in `services/pubsub/policy.py` (`user.{uid}.*` private, `public.*` shared, admin/internal anywhere, guests opt-in). In-process `services.pubsub.publish(topic, data)` for backends; frontend `app.pubsub`. See `devplacepy/services/pubsub/CLAUDE.md` |
| (none) | seo.py - `/robots.txt`, `/sitemap.xml` |
+4 -1
View File
@@ -2,7 +2,10 @@
from fastapi import APIRouter
from . import spec
from . import devices, spec, ticket, ws
router = APIRouter()
router.include_router(spec.router)
router.include_router(devices.router)
router.include_router(ticket.router)
router.include_router(ws.router)
+25
View File
@@ -0,0 +1,25 @@
# retoor <retoor@molodetz.nl>
from devplacepy.database.nodes import effective_status
from devplacepy.schemas.nodes import NodeDeviceOut
from devplacepy.services.nodes.consent import ConsentGate
GATE = ConsentGate()
NODES_SCOPE = "nodes"
NO_STORE = {"Cache-Control": "no-store"}
def device_view(row: dict) -> NodeDeviceOut:
return NodeDeviceOut(
uid=row["uid"],
label=row.get("label") or "",
kind=row.get("kind") or "",
platform=row.get("platform") or "",
client_version=row.get("client_version") or "",
status=effective_status(row),
suspended_until=row.get("suspended_until") or None,
country=row.get("country") or "",
asn_class=row.get("asn_class") or "unknown",
last_seen_at=row.get("last_seen_at") or None,
created_at=row.get("created_at"),
)
+142
View File
@@ -0,0 +1,142 @@
# retoor <retoor@molodetz.nl>
import logging
from typing import Annotated
from fastapi import APIRouter, Depends, Request
from fastapi.responses import JSONResponse
from devplacepy.database.nodes import (
LIMITS,
NodeLimitError,
create_device,
get_device,
list_devices,
revoke_device,
rotate_device_secret,
)
from devplacepy.dependencies import json_or_form
from devplacepy.models import NodeDeviceForm
from devplacepy.responses import json_error
from devplacepy.routers.nodes._shared import GATE, NO_STORE, device_view
from devplacepy.schemas.nodes import (
NodeDeviceCreatedOut,
NodeDevicesOut,
NodeSecretOut,
)
from devplacepy.services.audit import record as audit
from devplacepy.utils import is_admin, require_user_api
logger = logging.getLogger(__name__)
router = APIRouter()
def _json(model, status_code: int = 200) -> JSONResponse:
return JSONResponse(
model.model_dump(mode="json"), status_code=status_code, headers=NO_STORE
)
@router.get("/devices")
async def list_my_devices(request: Request):
user = require_user_api(request)
return _json(
NodeDevicesOut(
devices=[device_view(row) for row in list_devices(user["uid"])],
max_devices=LIMITS.max_devices_per_user,
)
)
@router.post("/devices")
async def create_my_device(
request: Request,
data: Annotated[NodeDeviceForm, Depends(json_or_form(NodeDeviceForm))],
):
user = require_user_api(request)
verdict = GATE.allows(user["uid"])
if not verdict.allowed:
audit.record(
request,
"node.device.create",
user=user,
result="denied",
target_type="node_device",
metadata={"reason": verdict.reason},
summary=f"device registration refused: {verdict.reason}",
)
return json_error(403, verdict.message, reason=verdict.reason)
try:
row, secret = create_device(
user["uid"],
data.label,
data.kind,
platform=data.platform,
client_version=data.client_version,
)
except NodeLimitError as exc:
return json_error(409, str(exc))
audit.record(
request,
"node.device.create",
user=user,
target_type="node_device",
target_uid=row["uid"],
target_label=row["label"],
metadata={"kind": row["kind"]},
summary=f"registered {row['kind']} device {row['label'] or row['uid']}",
)
return _json(
NodeDeviceCreatedOut(device=device_view(row), secret=secret), status_code=201
)
@router.post("/devices/{device_uid}/rotate")
async def rotate_my_device(request: Request, device_uid: str):
user = require_user_api(request)
row = get_device(device_uid)
if row is None or row["user_uid"] != user["uid"]:
return json_error(404, "Device not found")
secret = rotate_device_secret(device_uid, user["uid"])
if secret is None:
return json_error(404, "Device not found")
audit.record(
request,
"node.device.rotate",
user=user,
target_type="node_device",
target_uid=device_uid,
target_label=row["label"],
summary=f"rotated the secret of device {row['label'] or device_uid}",
)
return _json(NodeSecretOut(uid=device_uid, secret=secret))
@router.post("/devices/{device_uid}/delete")
async def delete_my_device(request: Request, device_uid: str):
user = require_user_api(request)
row = get_device(device_uid)
if row is None:
return json_error(404, "Device not found")
if row["user_uid"] != user["uid"] and not is_admin(user):
audit.record(
request,
"security.authz.denied",
user=user,
result="denied",
target_type="node_device",
target_uid=device_uid,
summary="non-owner denied deleting a node device",
)
return json_error(403, "Only the owner or an administrator can delete a device")
revoke_device(device_uid, user["uid"])
audit.record(
request,
"node.device.delete",
user=user,
target_type="node_device",
target_uid=device_uid,
target_label=row["label"],
summary=f"deleted device {row['label'] or device_uid}",
)
return JSONResponse({"ok": True}, headers=NO_STORE)
+52
View File
@@ -0,0 +1,52 @@
# retoor <retoor@molodetz.nl>
from fastapi import APIRouter, Request
from fastapi.responses import JSONResponse
from devplacepy.database.nodes import (
LIMITS,
SECRET_PREFIX,
STATUS_ACTIVE,
effective_status,
find_device_by_secret,
)
from devplacepy.responses import json_error
from devplacepy.routers.nodes._shared import GATE, NO_STORE, NODES_SCOPE
from devplacepy.schemas.nodes import NodeTicketOut
from devplacepy.services.messaging.tickets import issue_ticket
router = APIRouter()
BEARER = "bearer "
def _secret(request: Request) -> str:
header = request.headers.get("authorization", "")
if header.lower().startswith(BEARER):
return header[len(BEARER):].strip()
return ""
@router.post("/ticket")
async def node_ticket(request: Request):
secret = _secret(request)
if not secret.startswith(SECRET_PREFIX):
return json_error(401, "A device secret is required")
device = find_device_by_secret(secret)
if device is None:
return json_error(401, "Unknown device secret")
if effective_status(device) != STATUS_ACTIVE:
return json_error(403, "This device is suspended", reason="suspended")
verdict = GATE.allows(device["user_uid"])
if not verdict.allowed:
return json_error(403, verdict.message, reason=verdict.reason)
token = issue_ticket(
device["user_uid"],
scope=NODES_SCOPE,
device_uid=device["uid"],
ttl_seconds=LIMITS.ticket_ttl_seconds,
)
body = NodeTicketOut(
ticket=token, expires_in=LIMITS.ticket_ttl_seconds, ws_path="/nodes/ws"
)
return JSONResponse(body.model_dump(mode="json"), headers=NO_STORE)
+107
View File
@@ -0,0 +1,107 @@
# retoor <retoor@molodetz.nl>
import logging
from fastapi import APIRouter, WebSocket, WebSocketDisconnect
from devplacepy.database.nodes import (
STATUS_ACTIVE,
add_event,
effective_status,
get_device,
hash_ip,
record_device_connection,
)
from devplacepy.routers.nodes._shared import GATE, NODES_SCOPE
from devplacepy.services.manager import service_manager
from devplacepy.services.messaging.tickets import redeem_ticket_row
from devplacepy.services.nodes.frames import FrameError
from devplacepy.services.nodes.session import NodeSession
from devplacepy.services.nodes.spec import (
CLOSE_CAPACITY,
CLOSE_POLICY,
CLOSE_RETRY_OWNER,
)
logger = logging.getLogger(__name__)
router = APIRouter()
TRY_AGAIN_LATER = 1013
def _address(websocket: WebSocket) -> str:
forwarded = websocket.headers.get("x-real-ip", "")
if forwarded:
return forwarded
return websocket.client.host if websocket.client else ""
@router.websocket("/ws")
async def node_ws(websocket: WebSocket, ticket: str = ""):
await websocket.accept()
service = service_manager.get_service("nodes")
if service is None or not service.is_enabled():
await websocket.close(code=TRY_AGAIN_LATER)
return
if not service_manager.owns_lock():
await websocket.close(code=CLOSE_RETRY_OWNER)
return
registry, counters = service.registry, service.counters
row = redeem_ticket_row(ticket, NODES_SCOPE)
if row is None:
counters.inc("rejected_ticket")
await websocket.close(code=CLOSE_POLICY, reason="ticket")
return
device = get_device(row.get("device_uid") or "")
if (
device is None
or device["user_uid"] != row["user_uid"]
or effective_status(device) != STATUS_ACTIVE
):
counters.inc("rejected_device")
await websocket.close(code=CLOSE_POLICY, reason="device")
return
verdict = GATE.allows(device["user_uid"])
if not verdict.allowed:
counters.inc("rejected_consent")
await websocket.close(code=CLOSE_POLICY, reason=verdict.reason)
return
session = NodeSession(websocket, device)
admitted, previous = registry.admit(session)
if not admitted:
await websocket.close(code=CLOSE_CAPACITY, reason="capacity")
return
if previous is not None:
await previous.kick("replaced")
ended = "disconnect"
try:
hello = await session.handshake()
record_device_connection(
device["uid"],
platform=hello["platform"],
client_version=hello["client_version"],
protocol_version=hello["protocol"],
ip_hash=hash_ip(_address(websocket)),
)
add_event("connect", device_uid=device["uid"], user_uid=device["user_uid"])
ended = await session.run()
except FrameError as exc:
counters.inc("protocol_errors")
ended = exc.code
await session.close(exc.close_code, exc.code)
except WebSocketDisconnect:
pass
except Exception:
logger.exception("node socket failed")
ended = "error"
await session.close(CLOSE_POLICY, "error")
finally:
if ended == "heartbeat":
counters.inc("evicted_heartbeat")
registry.release(session)
add_event(
"disconnect",
device_uid=device["uid"],
user_uid=device["user_uid"],
detail=ended,
)
+22 -1
View File
@@ -7,6 +7,7 @@ from fastapi import APIRouter, Depends, Request
from devplacepy.database import (
CONSENT_KINDS,
MEMBER_ONLY_CONSENTS,
consent_state,
get_setting,
get_table,
@@ -15,7 +16,7 @@ from devplacepy.database import (
)
from devplacepy.dependencies import json_or_form
from devplacepy.models import ConsentForm, MaturePreferenceForm
from devplacepy.responses import action_result
from devplacepy.responses import action_result, json_error
from devplacepy.routers.profile.delete import _owner_only
from devplacepy.services.audit import record as audit
from devplacepy.utils import clear_user_cache
@@ -24,6 +25,7 @@ logger = logging.getLogger(__name__)
router = APIRouter()
TRUTHY = ("1", "on", "true", "yes")
AGENT_HEADER = "x-devii-agent"
VERSION_KEYS = {"terms": "terms_version", "privacy": "privacy_version"}
@@ -62,6 +64,25 @@ async def set_user_consent(
if denied is not None:
return denied
granted = data.granted.strip().lower() in TRUTHY
if (
granted
and data.kind in MEMBER_ONLY_CONSENTS
and request.headers.get(AGENT_HEADER) == "1"
):
audit.record(
request,
"security.authz.denied",
result="denied",
target_type="user",
target_uid=target["uid"],
target_label=target["username"],
metadata={"kind": data.kind, "reason": "agent cannot grant"},
summary=f"agent denied granting {data.kind} consent",
)
return json_error(
403,
"This consent can only be given by the member in their own privacy settings",
)
before = consent_state("user", target["uid"], data.kind)
set_consent(
"user", target["uid"], data.kind, granted, version=consent_version(data.kind)
+7
View File
@@ -205,6 +205,13 @@ from devplacepy.schemas.game import (
GameQuestOut,
GameStateOut,
)
from devplacepy.schemas.nodes import (
NodeDeviceCreatedOut,
NodeDeviceOut,
NodeDevicesOut,
NodeSecretOut,
NodeTicketOut,
)
from devplacepy.schemas.skills import (
SkillDetailOut,
SkillInstallOut,
+42
View File
@@ -0,0 +1,42 @@
# retoor <retoor@molodetz.nl>
from __future__ import annotations
from typing import Optional
from devplacepy.schemas.base import _Out
class NodeDeviceOut(_Out):
uid: str = ""
label: str = ""
kind: str = ""
platform: str = ""
client_version: str = ""
status: str = "active"
suspended_until: Optional[str] = None
country: str = ""
asn_class: str = "unknown"
last_seen_at: Optional[str] = None
created_at: Optional[str] = None
class NodeDevicesOut(_Out):
devices: list[NodeDeviceOut] = []
max_devices: int = 0
class NodeDeviceCreatedOut(_Out):
device: NodeDeviceOut
secret: str
class NodeSecretOut(_Out):
uid: str
secret: str
class NodeTicketOut(_Out):
ticket: str
expires_in: int
ws_path: str
+1
View File
@@ -49,6 +49,7 @@ CATEGORY_BY_PREFIX: dict[str, str] = {
"telegram": "telegram",
"devii": "devii",
"skill": "devii",
"node": "nodes",
"email": "email",
"cli": "cli",
"reward": "reward",
@@ -166,7 +166,10 @@ MODERATION_ACTIONS: tuple[Action, ...] = (
summary="Grant or withdraw one consent on your own account",
description=(
f"Kinds: {CONSENT_CHOICES}. Withdrawal takes effect immediately. Only the "
"account holder can change a consent, administrators included."
"account holder can change a consent, administrators included. Consents "
"that let other people use the member's own resources (bandwidth_sharing) "
"can be withdrawn here but are only granted by the member in their own "
"privacy settings."
),
params=(
path("username", "Your own username."),
+1
View File
@@ -31,6 +31,7 @@ Lives on the existing messages router (no new router/prefix; already mounted at
Short-lived, single-use tokens that let a browser-based WebSocket authenticate without ever needing to set a request header on the handshake. `POST /messages/ws-ticket` (`require_user`, so it accepts the same HTTP-reachable auth as any other guarded route - session cookie, `X-API-KEY`, or `Authorization: Bearer` - over a normal fetch/XHR, where headers work fine) calls `issue_ticket(user_uid)` and returns `{"ticket": "<opaque hex token>", "expires_in": 30}`. The client then opens `wss://.../messages/ws?ticket=<ticket>` - a query parameter, which a WS handshake CAN carry.
- `issue_ticket(user_uid) -> str` inserts a `ws_tickets` row (`uid` uuid7, `token` = `secrets.token_hex(24)`, `user_uid`, `created_at`, `expires_at` = now + 30s, `used_at=None`) and returns the token.
- `ws_tickets` also carries `scope` (empty or `messages` for chat, `nodes` for the node socket) and `device_uid`. `redeem_ticket_row(token, scope)` is the one conditional `UPDATE` (single use, unexpired, `COALESCE(scope, 'messages') = :scope`), so a node ticket can never open a chat socket and the reverse. `issue_ticket(user_uid, scope=, device_uid=, ttl_seconds=)`.
- `redeem_ticket(token) -> Optional[str]` looks the row up by `token`; returns `None` if missing, already used (`used_at` set), or past `expires_at`; otherwise stamps `used_at` and returns the `user_uid`. Redemption is single-use by construction - a ticket leaked via referrer or browser history cannot be replayed once redeemed, and it self-expires after 30 seconds even if never used.
- `ws_tickets` is NOT in `SOFT_DELETE_TABLES` - it is an ephemeral, single-use artifact, garbage-collected hard via `devplace messaging prune-tickets` (deletes rows where `expires_at < now`), the same shape as the zip/fork/backup `prune` CLI commands. `database/schema.py` `init_db()` ensures its columns (`uid`, `token`, `user_uid`, `created_at`, `expires_at`, `used_at`) and a unique index on `token` (the hot lookup path) plus an index on `expires_at` (the prune sweep).
- This is strictly additive to `_resolve_ws_user` - the existing session-cookie and header paths are completely unchanged, so `mode="page"` behavior and every existing non-browser API consumer are unaffected.
+18 -6
View File
@@ -9,18 +9,26 @@ from devplacepy.utils import generate_uid
TICKET_KEY_BYTES = 24
TICKET_TTL_SECONDS = 30
MESSAGES_SCOPE = "messages"
def issue_ticket(user_uid: str) -> str:
def issue_ticket(
user_uid: str,
scope: str = MESSAGES_SCOPE,
device_uid: str = "",
ttl_seconds: int = TICKET_TTL_SECONDS,
) -> str:
tickets = get_table("ws_tickets")
token = secrets.token_hex(TICKET_KEY_BYTES)
now = datetime.now(timezone.utc)
expires_at = (now + timedelta(seconds=TICKET_TTL_SECONDS)).isoformat()
expires_at = (now + timedelta(seconds=ttl_seconds)).isoformat()
tickets.insert(
{
"uid": generate_uid(),
"token": token,
"user_uid": user_uid,
"scope": scope,
"device_uid": device_uid,
"created_at": now.isoformat(),
"expires_at": expires_at,
"used_at": None,
@@ -29,7 +37,7 @@ def issue_ticket(user_uid: str) -> str:
return token
def redeem_ticket(token: str) -> Optional[str]:
def redeem_ticket_row(token: str, scope: str = MESSAGES_SCOPE) -> Optional[dict]:
if not token:
return None
from sqlalchemy import text
@@ -40,11 +48,15 @@ def redeem_ticket(token: str) -> Optional[str]:
text(
"UPDATE ws_tickets SET used_at = :now"
" WHERE token = :token AND used_at IS NULL AND expires_at >= :now"
" AND COALESCE(scope, 'messages') = :scope"
),
{"now": now, "token": token},
{"now": now, "token": token, "scope": scope},
)
if result.rowcount != 1:
return None
tickets = get_table("ws_tickets")
row = tickets.find_one(token=token)
return get_table("ws_tickets").find_one(token=token)
def redeem_ticket(token: str) -> Optional[str]:
row = redeem_ticket_row(token, MESSAGES_SCOPE)
return row.get("user_uid") if row else None
+27 -3
View File
@@ -2,7 +2,7 @@ This file documents the community node network (`devplacepy/services/nodes/`, `d
## What exists today
Phase 1 (the specification) and Phase 2 (the data layer and usage ledger) are built. Everything else is planned and listed under "Gaps" next to the phase that closes it. Nothing here is enabled for any account.
Phase 1 (the specification), Phase 2 (the data layer and usage ledger) and Phase 3 (registry, session, consent gate, kill switch, device and ticket routes, the lock-owner socket) are built. No job traffic flows yet. Everything else is planned and listed under "Gaps" next to the phase that closes it. Nothing here is enabled for any account.
| Piece | File | State |
|-------|------|-------|
@@ -12,7 +12,14 @@ Phase 1 (the specification) and Phase 2 (the data layer and usage ledger) are bu
| API docs group | `docs_api/groups/nodes.py` | built, one endpoint |
| Tables and helpers | `database/nodes.py`, `NODES_COLUMNS` in `database/schema.py` | built, tested, no route uses them yet |
| Usage ledger | `ledger.py` (`UsageLedger`, `DonationSummary`) | built, tested |
| `bandwidth_sharing` consent kind | `CONSENT_KINDS` in `database/moderation.py` | registered, never granted by default, enforced nowhere yet |
| `bandwidth_sharing` consent kind | `CONSENT_KINDS` in `database/moderation.py` | registered, never granted by default, enforced by `ConsentGate` |
| Frame codec | `frames.py` (`decode`, `encode`, `FrameError`) | built, tested, validates every frame against `spec.py` |
| Consent choke point | `consent.py` (`ConsentGate`, `Verdict`) | built, tested, single and batch |
| Socket session | `session.py` (`NodeSession`) | built, tested with a fake socket and a real one |
| Registry and counters | `registry.py` (`NodeRegistry`, `NodeCounters`) | built, tested |
| Supervisor | `service.py` (`NodesService`) | built, registered in `main.py`, default enabled |
| Device, ticket and socket routes | `routers/nodes/devices.py`, `ticket.py`, `ws.py` | built, tested |
| nginx upgrade block for `/nodes/ws` | `nginx/nginx.conf.template` | added |
## The specification is the contract
@@ -49,6 +56,23 @@ Seven tables, all ensured with their full column set in `init_db` (`_ensure_node
- **Settings are clamped on write and on read** (`normalise_settings`): bandwidth to `1..max_donor_mb_per_day`, concurrency to `1..max_concurrent_per_node`, hours must be `HH:MM`, platforms are intersected with the spec's adapters. A member with no row is opted out.
- Site settings seeded in `init_db`: `nodes_enabled` (`0`), `nodes_max_total`, `nodes_daily_quota_user`, `nodes_daily_quota_guest`, `nodes_cache_ttl_seconds`, `nodes_social_via_nodes` (`0`). Like every seed, consumers pass the default to `get_setting` because the seed does not run on an empty database.
## Connecting a node (Phase 3)
1. A member consents to `bandwidth_sharing` and turns donation on for themselves (the profile UI for this is Phase 9; today it is `POST /profile/{username}/consent` and `save_node_settings`).
2. `POST /nodes/devices` registers a device and returns its `dpn_` secret once. `GET /nodes/devices`, `POST /nodes/devices/{uid}/rotate` and `/delete` manage it. All are `require_user_api` (401, never a redirect) and answer `Cache-Control: no-store`.
3. The node calls `POST /nodes/ticket` with `Authorization: Bearer dpn_...`. A session cookie or a member API key is not a device secret and gets 401. The ticket is a `ws_tickets` row with `scope="nodes"` and the device uid, valid `ticket_ttl_seconds`, redeemed by one conditional `UPDATE` (16 processes racing one ticket gave exactly one winner; a ticket of the wrong scope never redeems).
4. The node opens `WS /nodes/ws?ticket=...`. The route only runs on the service-lock owner (`4013` elsewhere, the client retries fast, the `/pubsub/ws` precedent). Order of refusal: service disabled `1013`, not the owner `4013`, bad ticket or device or status `1008`, consent gate `1008` with the reason, capacity `4029`, then the handshake.
5. `hello` must arrive within `hello_timeout_seconds`, with a supported `protocol`, a `kind` equal to the registered device kind and a non-empty list of known `modes`. The server answers `welcome` with the full limits and allowlist from the spec. A second connection of the same device kicks the first with `replaced`.
6. The session pings every `ping_seconds`; any frame from the client resets the missed counter and `missed_pings_before_evict` unanswered pings close it with `heartbeat`. `usage` frames are advisory and only summed on the session. Every other client frame is a protocol error until Phase 4 assigns jobs.
## The consent choke point
`ConsentGate` is the only place that decides whether a member's node may exist. `allows_many(user_uids)` decides a whole set with a fixed number of queries and `allows(uid)` is the one-element case of it, so the single and batch answers cannot diverge (a test compares them). Order of reasons: `kill_switch`, `no_account`, `deletion_pending`, `account_inactive`, `suspended`, `not_adult`, `no_consent`, `not_enabled`. It is called at device registration, ticket issue, socket accept and every supervisor tick. An account whose `age_band` is empty (created before age bands existed) is refused as not adult, loudly, rather than assumed adult.
`NodesService.reconcile` runs every `reconcile_seconds`, asks the gate once for all connected owners and loads all devices in one query, then kicks with a reason: `kill_switch`, `revoked`, `suspended`, or the gate's reason. This is why withdrawing the consent, switching donation off, deleting the device or flipping `nodes_enabled` takes effect within one tick even when the request landed on a different worker than the one holding the sockets. **Measured** (scratch SQLite, this machine, 2000 synthetic sessions): one tick costs about 110 ms; the per-session version of the same check cost about 1 ms per session, so 488 ms at 500 sessions and an extrapolated 2 s at 2000, which would have blocked the event loop for the whole tick. Do not reintroduce a per-session query in `reconcile`.
Withdrawal is member-only: `MEMBER_ONLY_CONSENTS` in `database/moderation.py` lists consents that Devii (header `X-Devii-Agent: 1`, resolved in `routers/profile/consent.py`) may withdraw but never grant, and the acceptance service lists `bandwidth_sharing` in `EXCLUDED_CONSENTS`.
## Two transports, two trust levels
`tunnel` (native client) relays raw TCP so TLS runs end to end between DevPlace and the destination: the donor cannot read or forge content. `fetch` (browser extension, which has no raw sockets) lets the donor read and forge the response, so every `fetch` result is verified and labelled. A plain web page or a service worker cannot do either (CORS, no sockets) and is out of scope for good.
@@ -56,7 +80,7 @@ Seven tables, all ensured with their full column set in `init_db` (`_ensure_node
## Gaps (what the next phases close)
- Phase 2 leftovers: the `bandwidth_sharing` consent can currently be granted through `POST /profile/{username}/consent` and by Devii's `set_consent` (Devii calls that route as the user). Nothing reads it yet, so it is inert, but Phase 3 must make Devii unable to grant it (Devii may read and withdraw) at the same time as `ConsentGate` lands. No XP or badge is awarded yet (`UsageLedger.claim_xp` only reserves the daily budget); the privacy page and app-store declarations are updated with the first phase that lets a device connect, because until then no personal data is collected.
- Phase 3: registry, session, the consent choke point, the kill switch, device and ticket routes, the lock-owner WebSocket, the nginx upgrade location.
- Phase 3 leftovers: `country`, `asn` and `asn_class` on a device are never filled (they stay `unknown`), so the datacenter exclusion (D6) is not enforced yet; it needs the offline ASN database from Phase 4. `last_seen_at` is written on connect only, not per heartbeat, so a device list cannot yet show who is online right now. The socket counters are per process and are shown in the service metrics only. The `devplace.net` front proxy idle timeout for a long-lived socket is unmeasured.
- Phase 4: broker, scheduler, dispatcher, destination policy, circuit breakers, result cache.
- Phase 5 onward: the reference client, adapters, the Go client, the extension, the profile UI, Devii tools, the CLI, the privacy and donor-terms pages, the legal gate.
- Not measured yet: Reddit and X success rates per address class, WebSocket idle timeouts through `pravda.education` and `devplace.net`, dispatcher tick cost against SQLite, socket capacity of one worker. The caps in `LimitSpec` are starting ceilings, not measurements.
+84
View File
@@ -0,0 +1,84 @@
# retoor <retoor@molodetz.nl>
from __future__ import annotations
from dataclasses import dataclass
from devplacepy.database import (
consent_granted_many,
get_setting,
get_users_by_uids,
is_account_active,
suspension_active,
)
from devplacepy.database.nodes import BATCH_SIZE, get_enabled_by_users
CONSENT_KIND = "bandwidth_sharing"
ADULT_BAND = "adult"
REASONS: dict[str, str] = {
"kill_switch": "Community donation is switched off",
"no_account": "Account not found",
"account_inactive": "Account is not active",
"deletion_pending": "Account is being deleted",
"suspended": "Account is suspended",
"not_adult": "Only adults can donate bandwidth",
"no_consent": "Bandwidth sharing consent has not been given",
"not_enabled": "Donation is turned off in the member's settings",
}
@dataclass(frozen=True)
class Verdict:
allowed: bool
reason: str = ""
@property
def message(self) -> str:
return REASONS.get(self.reason, "") if not self.allowed else ""
ALLOWED = Verdict(True)
class ConsentGate:
def switched_on(self) -> bool:
return get_setting("nodes_enabled", "0") == "1"
def decide(self, user: dict | None, consented: bool, enabled: bool) -> Verdict:
if not user:
return Verdict(False, "no_account")
if (user.get("deletion_requested_at") or "").strip():
return Verdict(False, "deletion_pending")
if not is_account_active(user):
return Verdict(False, "account_inactive")
if suspension_active(user):
return Verdict(False, "suspended")
if (user.get("age_band") or "") != ADULT_BAND:
return Verdict(False, "not_adult")
if not consented:
return Verdict(False, "no_consent")
if not enabled:
return Verdict(False, "not_enabled")
return ALLOWED
def allows_many(self, user_uids) -> dict[str, Verdict]:
unique = list(dict.fromkeys(uid for uid in user_uids))
if not self.switched_on():
return {uid: Verdict(False, "kill_switch") for uid in unique}
verdicts: dict[str, Verdict] = {}
for start in range(0, len(unique), BATCH_SIZE):
batch = unique[start : start + BATCH_SIZE]
users = get_users_by_uids(batch)
consented = consent_granted_many("user", batch, CONSENT_KIND)
enabled = get_enabled_by_users(batch)
for uid in batch:
verdicts[uid] = self.decide(
users.get(uid), uid in consented, enabled.get(uid, False)
)
return verdicts
def allows(self, user_uid: str) -> Verdict:
if not user_uid:
return Verdict(False, "kill_switch" if not self.switched_on() else "no_account")
return self.allows_many([user_uid])[user_uid]
+90
View File
@@ -0,0 +1,90 @@
# retoor <retoor@molodetz.nl>
from __future__ import annotations
import json
from typing import Any
from devplacepy.services.nodes.spec import (
CLIENT_TO_SERVER,
CLOSE_FRAME_TOO_LARGE,
CLOSE_PROTOCOL,
SPEC,
)
FIELD_TYPES: dict[str, type] = {
"str": str,
"int": int,
"bool": bool,
"object": dict,
"list": list,
}
class FrameError(ValueError):
def __init__(self, code: str, reason: str, close_code: int = CLOSE_PROTOCOL):
super().__init__(reason)
self.code = code
self.reason = reason
self.close_code = close_code
def ceiling(direction: str) -> int:
return max(item.max_bytes for item in SPEC.frames if item.direction == direction)
def _matches(value: Any, type_name: str) -> bool:
expected = FIELD_TYPES[type_name]
if expected is int:
return isinstance(value, int) and not isinstance(value, bool)
return isinstance(value, expected)
def validate(frame: dict, direction: str) -> dict:
kind = frame.get("type")
spec = SPEC.frame(kind, direction) if isinstance(kind, str) else None
if spec is None:
raise FrameError("unknown_frame", f"unknown frame type {kind!r}")
unexpected = set(frame) - spec.allowed()
if unexpected:
raise FrameError("unexpected_field", f"unexpected field {sorted(unexpected)[0]}")
for item in spec.fields:
if item.name not in frame:
if item.required:
raise FrameError("missing_field", f"missing field {item.name}")
continue
if not _matches(frame[item.name], item.type):
raise FrameError("bad_field_type", f"field {item.name} must be {item.type}")
return frame
def decode(raw: str | bytes, direction: str = CLIENT_TO_SERVER) -> dict:
size = len(raw.encode()) if isinstance(raw, str) else len(raw)
if size > ceiling(direction):
raise FrameError(
"frame_too_large", "frame exceeds the size cap", CLOSE_FRAME_TOO_LARGE
)
try:
frame = json.loads(raw)
except ValueError:
raise FrameError("bad_json", "frame is not valid JSON")
if not isinstance(frame, dict):
raise FrameError("bad_json", "frame must be a JSON object")
validate(frame, direction)
limit = SPEC.frame(frame["type"], direction).max_bytes
if size > limit:
raise FrameError(
"frame_too_large", "frame exceeds its size cap", CLOSE_FRAME_TOO_LARGE
)
return frame
def encode(frame_type: str, direction: str, **fields: Any) -> str:
frame = {"type": frame_type, **fields}
validate(frame, direction)
text = json.dumps(frame, separators=(",", ":"))
if len(text.encode()) > SPEC.frame(frame_type, direction).max_bytes:
raise FrameError(
"frame_too_large", "frame exceeds its size cap", CLOSE_FRAME_TOO_LARGE
)
return text
+84
View File
@@ -0,0 +1,84 @@
# retoor <retoor@molodetz.nl>
from __future__ import annotations
from collections import Counter
from devplacepy.database import get_int_setting
from devplacepy.services.nodes.session import NodeSession
from devplacepy.services.nodes.spec import SPEC
LIMITS = SPEC.limits
COUNTER_NAMES: tuple[str, ...] = (
"connected_total",
"rejected_capacity",
"rejected_ticket",
"rejected_consent",
"rejected_device",
"protocol_errors",
"evicted_heartbeat",
"kicked",
"replaced",
)
class NodeCounters:
def __init__(self) -> None:
self._counts: Counter[str] = Counter({name: 0 for name in COUNTER_NAMES})
def inc(self, name: str) -> None:
if name not in COUNTER_NAMES:
raise KeyError(name)
self._counts[name] += 1
def snapshot(self) -> dict[str, int]:
return {name: self._counts[name] for name in COUNTER_NAMES}
class NodeRegistry:
def __init__(self, counters: NodeCounters) -> None:
self._sessions: dict[str, NodeSession] = {}
self.counters = counters
def capacity(self) -> int:
configured = get_int_setting("nodes_max_total", LIMITS.max_connected_nodes)
return max(0, min(configured, LIMITS.max_connected_nodes))
def count(self) -> int:
return len(self._sessions)
def sessions(self) -> list[NodeSession]:
return list(self._sessions.values())
def get(self, device_uid: str) -> NodeSession | None:
return self._sessions.get(device_uid)
def by_user(self, user_uid: str) -> list[NodeSession]:
return [item for item in self._sessions.values() if item.user_uid == user_uid]
def admit(self, session: NodeSession) -> tuple[bool, NodeSession | None]:
previous = self._sessions.get(session.device_uid)
if previous is None and self.count() >= self.capacity():
self.counters.inc("rejected_capacity")
return False, None
self._sessions[session.device_uid] = session
self.counters.inc("connected_total")
if previous is not None:
self.counters.inc("replaced")
return True, previous
def release(self, session: NodeSession) -> None:
if self._sessions.get(session.device_uid) is session:
del self._sessions[session.device_uid]
async def kick(self, session: NodeSession, reason: str) -> None:
self.release(session)
self.counters.inc("kicked")
await session.kick(reason)
async def kick_all(self, reason: str) -> int:
sessions = self.sessions()
for session in sessions:
await self.kick(session, reason)
return len(sessions)
+131
View File
@@ -0,0 +1,131 @@
# retoor <retoor@molodetz.nl>
from __future__ import annotations
import logging
import time
from devplacepy.database.nodes import (
STATUS_ACTIVE,
add_event,
effective_status,
get_devices_by_uids,
)
from devplacepy.services.base import BaseService, ConfigField
from devplacepy.services.nodes.consent import ConsentGate
from devplacepy.services.nodes.ledger import UsageLedger
from devplacepy.services.nodes.registry import NodeCounters, NodeRegistry
from devplacepy.services.nodes.spec import SPEC
logger = logging.getLogger(__name__)
LIMITS = SPEC.limits
SERVICE_NAME = "nodes"
class NodesService(BaseService):
title = "Community nodes"
description = (
"Holds the connected donor nodes, enforces the consent gate and the kill "
"switch within one tick, and prunes the donation counters."
)
details = (
"Donation is off until an administrator turns it on here and a member has "
"consented, enabled it for themselves and registered a device. Switching it "
"off disconnects every node on the next tick. The service never bans a "
"member and never deletes a ledger row on its own."
)
min_interval = 1
METRICS_SECONDS = 5
config_fields = [
ConfigField(
"nodes_enabled",
"Community donation",
type="bool",
default=False,
help="Master kill switch. Off disconnects every node on the next tick.",
group="Safety",
),
ConfigField(
"nodes_max_total",
"Maximum connected nodes",
type="int",
default=LIMITS.max_connected_nodes,
minimum=0,
maximum=LIMITS.max_connected_nodes,
help="Hard ceiling on simultaneous sockets in this process.",
group="Safety",
),
]
def __init__(self) -> None:
super().__init__(SERVICE_NAME, interval_seconds=LIMITS.reconcile_seconds)
self.counters = NodeCounters()
self.registry = NodeRegistry(self.counters)
self.gate = ConsentGate()
self.ledger = UsageLedger()
self._last_prune = 0.0
async def reconcile(self) -> int:
sessions = self.registry.sessions()
if not sessions:
return 0
switched_on = self.gate.switched_on()
devices = get_devices_by_uids(item.device_uid for item in sessions)
verdicts = self.gate.allows_many(item.user_uid for item in sessions)
kicked = 0
for session in sessions:
reason = self._reason_to_kick(
switched_on, devices.get(session.device_uid), verdicts[session.user_uid]
)
if reason:
await self.registry.kick(session, reason)
add_event(
"kick",
device_uid=session.device_uid,
user_uid=session.user_uid,
detail=reason,
)
kicked += 1
return kicked
@staticmethod
def _reason_to_kick(switched_on: bool, device: dict | None, verdict) -> str:
if not switched_on:
return "kill_switch"
if device is None:
return "revoked"
if effective_status(device) != STATUS_ACTIVE:
return "suspended"
return "" if verdict.allowed else verdict.reason
def _prune_due(self) -> bool:
return time.monotonic() - self._last_prune >= LIMITS.prune_interval_seconds
async def run_once(self) -> None:
kicked = await self.reconcile()
if kicked:
self.log(f"disconnected {kicked} node(s)")
if self._prune_due():
self._last_prune = time.monotonic()
pruned = self.ledger.prune()
if any(pruned.values()):
self.log(f"pruned {pruned}")
async def on_disable(self) -> None:
await self.registry.kick_all("service_stopped")
def collect_metrics(self) -> dict:
counts = self.counters.snapshot()
return {
"stats": [
{"label": "connected", "value": self.registry.count()},
{"label": "capacity", "value": self.registry.capacity()},
{"label": "accepted", "value": counts["connected_total"]},
{"label": "kicked", "value": counts["kicked"]},
],
"table": {
"columns": ["counter", "value"],
"rows": [[name, value] for name, value in counts.items()],
},
}
+113
View File
@@ -0,0 +1,113 @@
# retoor <retoor@molodetz.nl>
from __future__ import annotations
import asyncio
import time
from devplacepy.database.nodes import get_node_settings
from devplacepy.services.nodes.frames import FrameError, decode, encode
from devplacepy.services.nodes.spec import (
CLIENT_TO_SERVER,
CLOSE_KICKED,
CLOSE_POLICY,
MODES,
SERVER_TO_CLIENT,
SPEC,
)
LIMITS = SPEC.limits
END_HEARTBEAT = "heartbeat"
END_UNEXPECTED_FRAME = "unexpected_frame"
class NodeSession:
def __init__(self, websocket, device: dict) -> None:
self.websocket = websocket
self.device = device
self.device_uid: str = device["uid"]
self.user_uid: str = device["user_uid"]
self.connected_at = time.monotonic()
self.missed_pings = 0
self.hello: dict = {}
self.reported_up = 0
self.reported_down = 0
self.closed = False
async def send(self, frame_type: str, **fields) -> None:
await self.websocket.send_text(encode(frame_type, SERVER_TO_CLIENT, **fields))
async def close(self, code: int, reason: str = "") -> None:
if self.closed:
return
self.closed = True
try:
await self.websocket.close(code=code, reason=reason[:120])
except Exception:
pass
async def kick(self, reason: str) -> None:
if self.closed:
return
try:
await self.send("kick", reason=reason)
except Exception:
pass
await self.close(CLOSE_KICKED, reason)
def _check_hello(self, frame: dict) -> None:
if not SPEC.min_supported <= frame["protocol"] <= SPEC.version:
raise FrameError("protocol_unsupported", "protocol version is not supported", CLOSE_POLICY)
if frame["kind"] != self.device.get("kind"):
raise FrameError("kind_mismatch", "client kind does not match the registered device", CLOSE_POLICY)
if not frame["modes"] or any(mode not in MODES for mode in frame["modes"]):
raise FrameError("bad_modes", "modes must be a non-empty list of known modes")
async def handshake(self) -> dict:
try:
raw = await asyncio.wait_for(
self.websocket.receive_text(), timeout=LIMITS.hello_timeout_seconds
)
except asyncio.TimeoutError:
raise FrameError("hello_timeout", "no hello frame arrived in time", CLOSE_POLICY)
frame = decode(raw, CLIENT_TO_SERVER)
if frame["type"] != "hello":
raise FrameError("expected_hello", "the first frame must be hello")
self._check_hello(frame)
self.hello = frame
await self.send(
"welcome",
device_uid=self.device_uid,
limits=LIMITS.describe(),
destinations=[item.describe() for item in SPEC.destinations],
settings=get_node_settings(self.user_uid),
)
return frame
def _handle(self, frame: dict) -> None:
kind = frame["type"]
if kind == "pong":
return
if kind == "usage":
self.reported_up += max(0, frame["bytes_up"])
self.reported_down += max(0, frame["bytes_down"])
return
raise FrameError(END_UNEXPECTED_FRAME, f"unexpected {kind} frame, no job is assigned")
async def run(self) -> str:
while not self.closed:
try:
raw = await asyncio.wait_for(
self.websocket.receive_text(), timeout=LIMITS.ping_seconds
)
except asyncio.TimeoutError:
if self.missed_pings >= LIMITS.missed_pings_before_evict:
await self.close(CLOSE_POLICY, END_HEARTBEAT)
return END_HEARTBEAT
self.missed_pings += 1
await self.send("ping")
continue
self.missed_pings = 0
self._handle(decode(raw, CLIENT_TO_SERVER))
return "closed"
+3
View File
@@ -94,6 +94,9 @@ class LimitSpec:
request_retention_seconds: int = 600
xp_daily_cap: int = 50
dispatcher_tick_ms: int = 200
hello_timeout_seconds: int = 10
reconcile_seconds: int = 2
prune_interval_seconds: int = 3600
def describe(self) -> dict[str, int]:
return dict(self.__dict__)
@@ -3,7 +3,7 @@
This page is generated from the protocol specification, `services/nodes/spec.py`, the same data served at [`/nodes/spec.json`](/nodes/spec.json). The server, the clients, the tests and this page all read that one source, so the numbers below cannot drift from the code.
**Status today:** the specification and `/nodes/spec.json` exist. The node socket, the device registration, the consent flow and the clients are not implemented yet. Nothing on this page is enabled for any account.
**Status today:** the specification, `/nodes/spec.json`, device registration, the socket ticket, the node socket and the consent gate are implemented on the server and are switched off by default. The clients and the search integration are not built yet, so no node can do anything useful and no job is ever sent. Nothing on this page is enabled for any account.
## Rules that never change