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:
@@ -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",
|
||||
|
||||
@@ -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:
|
||||
|
||||
@@ -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(
|
||||
|
||||
@@ -498,6 +498,8 @@ def init_db():
|
||||
("uid", ""),
|
||||
("token", ""),
|
||||
("user_uid", ""),
|
||||
("scope", ""),
|
||||
("device_uid", ""),
|
||||
("created_at", ""),
|
||||
("expires_at", ""),
|
||||
("used_at", ""),
|
||||
|
||||
@@ -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.",
|
||||
],
|
||||
),
|
||||
],
|
||||
}
|
||||
|
||||
@@ -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())
|
||||
|
||||
@@ -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)
|
||||
|
||||
@@ -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` |
|
||||
|
||||
|
||||
@@ -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)
|
||||
|
||||
@@ -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"),
|
||||
)
|
||||
@@ -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)
|
||||
@@ -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)
|
||||
@@ -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,
|
||||
)
|
||||
@@ -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)
|
||||
|
||||
@@ -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,
|
||||
|
||||
@@ -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
|
||||
@@ -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."),
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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]
|
||||
@@ -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
|
||||
@@ -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)
|
||||
@@ -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()],
|
||||
},
|
||||
}
|
||||
@@ -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"
|
||||
@@ -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
|
||||
|
||||
|
||||
Reference in New Issue
Block a user