Panels become devices: per-device documents in the flow repo, a Devices tab

- flow/devices.py: DeviceDef in FLOWS_DIR/_devices/<id>.json, committed under
  the flow store's write lock, 409 on a stale version; nonces in DEVICES_FILE
  outside git; in-memory presence announced as device_status
- api/routes/devices.py: CRUD, pairing with an optional {name, board,
  firmware}, a pending list adopted without a code from the LAN only, unpair;
  /panels/pair, /panels/pair/{code} and GET /panels/{id} kept as aliases,
  PUT /panels/ gone
- _device_may replaces _panel_may, JWT claims unchanged
- panels.json moves into devices once at startup, then .migrated
- MCP list_devices, get_device; search category device
- Devices tab (list, detail with presence, pairing, ordered dashboards,
  touch, I/O), PanelsDialog removed, serialised optimistic saves
This commit is contained in:
Melvin Strobl
2026-10-16 15:48:36 +02:00
parent 3c0912a3fe
commit 28a565e501
56 changed files with 3539 additions and 2404 deletions
+96 -61
View File
@@ -15,10 +15,11 @@ from fluksio.cloud import enroll
from fluksio.core import security
from fluksio.core.config import settings
from fluksio.core.db import engine
from fluksio.flow import panels
from fluksio.flow import devices
from fluksio.flow.artifacts import is_reference
from fluksio.flow.controller import FlowController
from fluksio.flow.dashboards import DashboardDef, DashboardStore
from fluksio.flow.devices import DeviceDef, DeviceStore, presence
from fluksio.flow.workers import PythonWorkerPool
from fluksio.models import OAuthClient, TokenPayload, User, WorkerToken
@@ -40,35 +41,46 @@ TokenDep = Annotated[str, Depends(reusable_oauth2)]
#: literals; anything else is refused rather than guessed at.
_NOT_DRAFT = {"false", "0", "off", "f", "n", "no", ""}
#: The one route under a message name a panel reads.
#: The one route under a message name a device reads.
_HISTORY = "/history"
def _panel_for(payload: dict[str, Any]) -> panels.PanelDef:
"""The panel a credential names, if that credential still stands.
def _device_for(payload: dict[str, Any], app: Any) -> DeviceDef:
"""The device a credential names, if that credential still stands.
Two ways it stops standing. The panel was deleted, which revokes every
credential ever minted for it — read from disk on each call, so it takes
effect at once. Or the panel's nonce moved on, which revokes exactly one
screen's and leaves the panel, its dashboards and their arrangement alone.
Two ways it stops standing. The device was deleted, which revokes every
credential ever minted for it, read from disk on each call so it takes
effect at once. Or the device's nonce moved on, which revokes exactly one
screen's and leaves the device and its dashboards alone.
The nonce is only held against a credential this instance signed. One
the portal minted for a remote screen carries none — the portal names the
panel and nothing else — and is revoked at the hub instead.
The nonce is only held against a credential this instance signed. One the
portal minted for a remote screen carries none, the portal names the
device and nothing else, and is revoked at the hub instead.
The claim is still called ``panel``: tokens in circulation say it, and
nothing pairs again for a rename.
"""
panel = panels.find(str(payload.get("panel", "")))
if panel is None:
raise InvalidTokenError("This panel no longer exists")
if (
payload.get("aud") == security.PANEL_AUDIENCE
and int(payload.get("pnc") or 0) != panel.nonce
):
raise InvalidTokenError("This panel was paired with another device")
return panel
store: DeviceStore | None = (
getattr(app.state, "device_store", None) if app else None
)
if store is None:
raise InvalidTokenError("The device store is not running")
device = store.find(str(payload.get("panel", "")))
if device is None:
raise InvalidTokenError("This device no longer exists")
if payload.get("aud") == security.PANEL_AUDIENCE:
try:
nonce = store.nonce(device.id)
except (OSError, ValueError) as exc:
raise InvalidTokenError(f"The device nonces are unreadable: {exc}")
if int(payload.get("pnc") or 0) != nonce:
raise InvalidTokenError("This device was paired again")
presence.seen(device.id)
return device
def _panel_messages(panel_id: str, request: Request) -> set[str]:
"""Every message this panel's widgets read or write.
def _device_messages(device: DeviceDef, request: Request) -> set[str]:
"""Every message this device's widgets and ports read or write.
The same walk that bounds its socket, so the two surfaces a screen has
agree on what it is entitled to. No store means nothing resolves, which is
@@ -77,7 +89,7 @@ def _panel_messages(panel_id: str, request: Request) -> set[str]:
store: DashboardStore | None = getattr(request.app.state, "dashboard_store", None)
if store is None:
return set()
return panels.messages_for(panel_id, store)
return devices.messages_for(device, store)
def _locked(defn: DashboardDef, live: dict[str, Any]) -> bool:
@@ -96,8 +108,8 @@ def _locked(defn: DashboardDef, live: dict[str, Any]) -> bool:
return (setting.value if value is None else value) is True
def _panel_writable(panel_id: str, request: Request) -> set[str]:
"""The messages this panel may publish to.
def _device_writable(device: DeviceDef, request: Request) -> set[str]:
"""The messages this device may publish to.
What its dashboards' inputs target, which is narrower than what it may
read: a chart, a reading or a bound setting is something a screen shows,
@@ -109,7 +121,7 @@ def _panel_writable(panel_id: str, request: Request) -> set[str]:
that asked anyway. Not nothing, though: a querying chart publishes the
request it reads by, and a locked dashboard whose charts cannot ask goes
blank rather than read-only. That request is the exception
``panels.requests_of`` names.
``devices.requests_of`` names.
Union, exactly as the allowlist itself is: a message one dashboard on this
panel displays and another controls stays writable, because the unlocked
@@ -123,8 +135,8 @@ def _panel_writable(panel_id: str, request: Request) -> set[str]:
store: DashboardStore | None = getattr(request.app.state, "dashboard_store", None)
if store is None:
return set()
writable = panels.io_in(panel_id)
defns = panels.dashboards_for(panel_id, store)
writable = devices.io_in(device)
defns = devices.dashboards_for(device, store)
bound = sorted(
{s.message for d in defns if (s := d.settings.get("locked")) and s.message}
)
@@ -134,12 +146,14 @@ def _panel_writable(panel_id: str, request: Request) -> set[str]:
live = controller.state.get_present(bound) if bound and controller else {}
for defn in defns:
writable |= (
panels.requests_of(defn) if _locked(defn, live) else panels.targets_of(defn)
devices.requests_of(defn)
if _locked(defn, live)
else devices.targets_of(defn)
)
return writable
def _panel_digests(panel_id: str, request: Request) -> set[str]:
def _device_digests(device: DeviceDef, request: Request) -> set[str]:
"""The artifacts this panel's messages are pointing at right now.
A media tile fetches the bytes its message names, so the messages already
@@ -151,7 +165,7 @@ def _panel_digests(panel_id: str, request: Request) -> set[str]:
)
if controller is None:
return set()
names = _panel_messages(panel_id, request)
names = _device_messages(device, request)
if not names:
return set()
found: set[str] = set()
@@ -161,7 +175,7 @@ def _panel_digests(panel_id: str, request: Request) -> set[str]:
return found
def _panel_may(payload: dict[str, Any], request: Request) -> None:
def _device_may(payload: dict[str, Any], request: Request) -> None:
"""Refuse anything a wall panel has no business asking for.
A panel credential names the account that approved the pairing, so without
@@ -183,11 +197,11 @@ def _panel_may(payload: dict[str, Any], request: Request) -> None:
a panel to read every message it names and to publish to none of them but
the requests its own charts ask by.
# ponytail: the panel file and the published dashboards are re-read per
# request. Cache them behind the store's version if this shows up in a
# profile.
# ponytail: the device file, its nonce and the published dashboards are
# re-read per request. Cache them behind the store's revision if this
# shows up in a profile.
"""
panel = _panel_for(payload)
device = _device_for(payload, request.app)
api = settings.API_V1_STR
path = request.url.path
@@ -203,8 +217,12 @@ def _panel_may(payload: dict[str, Any], request: Request) -> None:
# fail-closed, so a spelling neither side recognises is a draft.
draft = request.query_params.get("draft")
published = draft is None or draft.lower() in _NOT_DRAFT
allowed = "/" not in name and name in panel.dashboards and published
elif method == "GET" and path == f"{api}/panels/{panel.id}":
allowed = "/" not in name and name in device.dashboards and published
elif method == "GET" and path in (
f"{api}/devices/{device.id}",
# What firmware from before devices reads.
f"{api}/panels/{device.id}",
):
allowed = True
elif method == "POST" and path == f"{api}/flows/ws-ticket":
# How its live socket opens; the socket applies the panel's own scope.
@@ -214,36 +232,38 @@ def _panel_may(payload: dict[str, Any], request: Request) -> None:
# value in. Percent-decoded, because a message name is a path segment
# here and the client encodes it as one.
rest = unquote(path[len(f"{api}/messages/") :])
scope = _panel_messages
scope = _device_messages
if method == "GET" and rest.endswith(_HISTORY):
name = rest[: -len(_HISTORY)]
elif method == "POST":
name = rest
# A locked dashboard entitles the panel to nothing it can publish.
scope = _panel_writable
scope = _device_writable
else:
name = ""
allowed = bool(name) and name in scope(panel.id, request)
allowed = bool(name) and name in scope(device, request)
elif method == "GET" and path.startswith(f"{api}/artifacts/"):
# The bytes behind a media message a tile on this panel is drawing.
# Scoped to what those messages hold *now*, which is exactly what a
# live widget asks for — a screen has no business reading an artifact
# off an old run because it happens to know the digest.
digest = unquote(path[len(f"{api}/artifacts/") :])
allowed = "/" not in digest and digest in _panel_digests(panel.id, request)
allowed = "/" not in digest and digest in _device_digests(device, request)
elif method == "PUT" and path == f"{api}/artifacts":
# What the device's own sensor recorded — a microphone's utterance —
# uploaded under the ``in`` message it is about to publish it to.
allowed = request.query_params.get("name", "") in panels.io_in(panel.id)
allowed = request.query_params.get("name", "") in devices.io_in(device)
if not allowed:
raise HTTPException(
status_code=status.HTTP_403_FORBIDDEN,
detail="A panel credential cannot do that",
detail="A device credential cannot do that",
)
def decode_token(token: str, request: Request | None = None) -> dict[str, Any]:
def decode_token(
token: str, request: Request | None = None, app: Any = None
) -> dict[str, Any]:
"""Read a bearer token, whichever channel issued it.
A browser session is signed with the app's own secret; an agent's token is
@@ -254,8 +274,9 @@ def decode_token(token: str, request: Request | None = None) -> dict[str, Any]:
A paired wall panel's token is signed with the app's secret too, and is
told apart from a session by its audience: the session decode above
refuses it outright, so the only door it fits is the one ``_panel_may``
guards.
refuses it outright, so the only door it fits is the one ``_device_may``
guards. Where there is no request to scope (a socket handshake, the
tunnel), ``app`` is what a device credential is checked against.
An agent's token is held to one thing more: the client it names has to
still be registered, which is what makes revoking an agent take effect now
@@ -286,11 +307,11 @@ def decode_token(token: str, request: Request | None = None) -> dict[str, Any]:
else:
if not panel_token.get("panel"):
raise InvalidTokenError("a panel token must name its panel")
return _gate_panel(panel_token, request)
return _gate_panel(panel_token, request, app)
try:
agent = security.decode_oauth_token(token)
except InvalidTokenError:
return _gate_panel(cloud_config.decode_portal_token(token), request)
return _gate_panel(cloud_config.decode_portal_token(token), request, app)
return _gate_agent(agent)
@@ -304,7 +325,7 @@ def oauth_client_lives(client_id: str) -> bool:
One primary-key read per agent request, against a table with a row per
registered agent. The request it gates goes on to look its user up the
same way, and the panel gate next door re-reads the panels file and every
same way, and the device gate next door re-reads the device's file and every
published dashboard from disk, so this is the cheapest check in here.
"""
try:
@@ -341,19 +362,22 @@ def _gate_agent(payload: dict[str, Any]) -> dict[str, Any]:
return payload
def _gate_panel(payload: dict[str, Any], request: Request | None) -> dict[str, Any]:
"""Scope a payload that names a panel; pass anything else through.
def _gate_panel(
payload: dict[str, Any], request: Request | None, app: Any = None
) -> dict[str, Any]:
"""Scope a payload that names a device; pass anything else through.
Without a request — from the websocket, which has no route to scope — the
check is only that the credential still stands, which is what makes
deleting a panel, or bumping its nonce, revoke one.
Without a request (the websocket, which has no route to scope) the check
is only that the credential still stands, which is what makes deleting a
device, or bumping its nonce, revoke one. Without an app either there is
nothing to check it against, and it is refused.
"""
if not payload.get("panel"):
return payload
if request is not None:
_panel_may(payload, request)
_device_may(payload, request)
else:
_panel_for(payload)
_device_for(payload, app)
return payload
@@ -393,17 +417,18 @@ def _user_for(session: Session, token_data: TokenPayload) -> User | None:
def user_from_token(
session: Session, token: str, request: Request | None = None
session: Session, token: str, request: Request | None = None, app: Any = None
) -> User | None:
"""Resolve a bearer token to its user, or None if it does not hold up.
Shared with the websocket, which cannot use the HTTP security scheme, and
with the artifact endpoint, which accepts a worker's credential as well as
a person's. Pass the request wherever there is one: a panel's credential is
scoped by route, and without it the scope check cannot run.
a person's. Pass the request wherever there is one: a device's credential is
scoped by route, and without it the scope check cannot run. Without one,
pass the app, or a device credential is refused.
"""
try:
token_data = TokenPayload(**decode_token(token, request))
token_data = TokenPayload(**decode_token(token, request, app))
except (InvalidTokenError, ValidationError):
return None
user = _user_for(session, token_data)
@@ -462,6 +487,16 @@ def get_dashboard_store(request: Request) -> DashboardStore:
DashboardStoreDep = Annotated[DashboardStore, Depends(get_dashboard_store)]
def get_device_store(request: Request) -> DeviceStore:
store: DeviceStore | None = getattr(request.app.state, "device_store", None)
if store is None:
raise HTTPException(status_code=503, detail="The flow engine is not running")
return store
DeviceStoreDep = Annotated[DeviceStore, Depends(get_device_store)]
def get_worker_pool(request: Request) -> PythonWorkerPool:
pool: PythonWorkerPool | None = getattr(request.app.state, "worker_pool", None)
if pool is None:
+4 -2
View File
@@ -7,6 +7,7 @@ from fluksio.api.routes import (
cloud,
connectors,
dashboards,
devices,
flavors,
flows,
login,
@@ -14,7 +15,6 @@ from fluksio.api.routes import (
modules,
oauth,
observability,
panels,
private,
runs,
search,
@@ -35,7 +35,9 @@ api_router.include_router(secrets.router)
api_router.include_router(connectors.router)
api_router.include_router(alerts.router)
api_router.include_router(dashboards.router)
api_router.include_router(panels.router)
api_router.include_router(devices.router)
# What the openpanel firmware calls today, on the same handlers.
api_router.include_router(devices.panels_router)
api_router.include_router(messages.router)
api_router.include_router(modules.router)
api_router.include_router(observability.router)
+679
View File
@@ -0,0 +1,679 @@
"""Devices: which dashboards a device shows, and how it gets a credential.
A wall tablet has no keyboard, so it cannot log in. It asks for a code instead,
shows it on the wall, and somebody with an account types that code into the
device's page to say which device it is, or picks the request from the list of
devices waiting on this network. The device polls, collects the credential the
approval minted, and never asks again.
A screen hanging somewhere this instance is not reachable from does the
same thing through the portal, which forwards the two pairing calls down the
tunnel without a session and mints the credential itself when the approval
comes. Anyone on the internet can ask the portal for a code, so a request that
came that way is adopted by its code only.
The credential is scoped: ``fluksio.api.deps`` lets it reach the dashboards
that device was assigned, the messages their widgets bind to, and nothing else.
Deleting the device revokes it, and so does unpairing, which bumps the
device's nonce and leaves what it shows as it was.
``/panels/pair``, ``/panels/pair/{code}`` and ``GET /panels/{id}`` are what the
openpanel firmware calls, and stay as aliases until every device has updated.
"""
from __future__ import annotations
import secrets
import time
from datetime import datetime, timedelta
from typing import Any, cast
import httpx
import redis
from fastapi import APIRouter, Depends, HTTPException, Request
from fastapi.concurrency import run_in_threadpool
from pydantic import BaseModel, Field, field_validator
from fluksio.api.deps import (
CurrentUser,
DeviceStoreDep,
get_current_active_superuser,
get_current_user,
)
from fluksio.cloud import config as cloud_config
from fluksio.core import security
from fluksio.core.config import settings
from fluksio.flow.devices import (
DeviceDef,
DeviceExists,
DeviceNotFound,
DeviceStore,
is_lan,
presence,
)
from fluksio.flow.events import event_bus
from fluksio.flow.state import CONNECT_TIMEOUT_S, SOCKET_TIMEOUT_S
from fluksio.flow.store import StaleVersion
from fluksio.models import Message, User
#: Gated per route rather than on the router: the pairing endpoints are the
#: only unauthenticated ones in the app, because a device with no credential is
#: the whole point of them.
router = APIRouter(prefix="/devices", tags=["devices"])
#: The calls the firmware makes today, on the same handlers.
panels_router = APIRouter(prefix="/panels", tags=["devices"], include_in_schema=False)
#: Long, because a device is a screen somebody hung once and left running, with
#: no keyboard to sign in again with. Same reasoning as a remote worker's.
TOKEN_DAYS = 365
#: How long a device's code is worth typing. Long enough to walk to a computer.
PAIR_TTL = 600
#: No I/O/0/1: the code is read off a wall and typed on a keyboard.
CODE_ALPHABET = "ABCDEFGHJKLMNPQRSTUVWXYZ23456789"
CODE_LENGTH = 6
#: Refuse to grow past this. Codes are free to ask for and cost memory.
MAX_PENDING = 50
#: Ids a device cannot take: the routes beside ``/{device_id}``.
RESERVED = {"pair", "pending"}
#: How much of what a device says about itself is kept.
HELLO_LENGTH = 64
class _Pending(BaseModel):
"""A device waiting to be told what it is."""
#: Held by the device, never shown.
secret: str
#: Names the request in the pending list, so it can be adopted without
#: the code being handed to anyone.
request: str = ""
#: Wall-clock rather than monotonic: an entry outlives the process that
#: minted it.
expires: float
token: str = ""
device_id: str = ""
#: What the request looked like, shown to whoever approves it so they can
#: tell the screen in the hall from one they were not expecting.
#: Self-reported and worth what that is worth.
device: str = ""
name: str = ""
board: str = ""
firmware: str = ""
#: Whether it came down the tunnel. A device that reached the portal
#: cannot reach this instance, so its credential has to be minted where it
#: can collect it.
remote: bool = False
#: Whether it may be adopted from the list without its code: asked from a
#: private network, not through the portal.
lan: bool = False
#: The entry itself, one key per code, expiring on its own.
_PENDING_KEY = "panels:pair"
#: An index of the live codes, so :data:`MAX_PENDING` means the same thing to
#: every worker. Scored by expiry, which is how it is pruned.
_PENDING_INDEX = "panels:pair:__codes__"
class _PendingStore:
"""The codes waiting for somebody to say what they are.
In Redis when there is one, so a code minted before a restart, or by
another process, is still found. Without one there is one process by
definition (the pip install, and the tests), and a dictionary is the same
thing for it.
"""
def __init__(self) -> None:
self._local: dict[str, _Pending] = {}
self._redis: redis.Redis | None = (
redis.Redis(
host=settings.REDIS_HOST,
port=settings.REDIS_PORT,
decode_responses=True,
# A silent Redis must fail this request, not hold it open.
socket_timeout=SOCKET_TIMEOUT_S,
socket_connect_timeout=CONNECT_TIMEOUT_S,
health_check_interval=30,
)
if settings.REDIS_HOST
else None
)
def _key(self, code: str) -> str:
return f"{_PENDING_KEY}:{code}"
def _codes(self) -> list[str]:
"""The live codes, the expired ones dropped first."""
now = time.time()
if self._redis is None:
for code in [c for c, e in self._local.items() if e.expires < now]:
del self._local[code]
return list(self._local)
self._redis.zremrangebyscore(_PENDING_INDEX, "-inf", now)
return list(cast("list[str]", self._redis.zrange(_PENDING_INDEX, 0, -1)))
def count(self) -> int:
return len(self._codes())
def waiting(self) -> list[tuple[str, _Pending]]:
"""Every code nobody has approved yet, with its entry."""
found = []
for code in self._codes():
entry = self.get(code)
if entry is not None and not entry.token:
found.append((code, entry))
return found
def add(self, code: str, entry: _Pending) -> bool:
"""Claim this code, or say that somebody already holds it."""
if self._redis is None:
if code in self._local:
return False
self._local[code] = entry
return True
if not self._redis.set(
self._key(code), entry.model_dump_json(), ex=PAIR_TTL, nx=True
):
return False
self._redis.zadd(_PENDING_INDEX, {code: entry.expires})
return True
def get(self, code: str) -> _Pending | None:
if self._redis is None:
entry = self._local.get(code)
else:
raw = cast("str | None", self._redis.get(self._key(code)))
entry = _Pending.model_validate_json(raw) if raw else None
return entry if entry is not None and entry.expires >= time.time() else None
def save(self, code: str, entry: _Pending) -> None:
"""Write an approval back, without moving what it expires at."""
if self._redis is None:
self._local[code] = entry
return
self._redis.set(
self._key(code),
entry.model_dump_json(),
ex=max(1, int(entry.expires - time.time())),
)
def drop(self, code: str) -> None:
if self._redis is None:
self._local.pop(code, None)
return
self._redis.delete(self._key(code))
self._redis.zrem(_PENDING_INDEX, code)
_pending = _PendingStore()
class PairHello(BaseModel):
"""What a device may say about itself when it asks for a code."""
name: str = ""
board: str = ""
firmware: str = ""
@field_validator("name", "board", "firmware", mode="before")
@classmethod
def _trim(cls, value: Any) -> str:
# Cut rather than refused: a device that says too much should still
# get its code.
return str(value or "").strip()[:HELLO_LENGTH]
class PairStarted(BaseModel):
"""What the device puts on the wall, and what it polls with."""
code: str
#: Held by the device, never shown. Without it the code alone would let
#: anyone who reads it off the wall collect the credential first.
secret: str
expires_in: int = PAIR_TTL
class PairStatus(BaseModel):
"""Nothing yet, or the credential and the device it is for."""
access_token: str | None = None
device: str | None = None
#: The same id, for firmware from before devices.
panel: str | None = None
class PairRequest(BaseModel):
"""Adopt the device showing ``code``, or the pending ``request``."""
code: str = ""
request: str = ""
class PendingDevice(BaseModel):
"""Who is asking, as far as the request itself says."""
#: What ``POST /devices/{id}/pair`` takes to adopt it without the code.
request: str = ""
device: str
name: str = ""
board: str = ""
firmware: str = ""
remote: bool = False
#: Through the portal or from outside this network: only its code adopts
#: it, since anyone can put a request there.
needs_code: bool = True
expires_in: int = 0
def _pending_public(entry: _Pending) -> PendingDevice:
return PendingDevice(
request=entry.request,
device=entry.device,
name=entry.name,
board=entry.board,
firmware=entry.firmware,
remote=entry.remote,
needs_code=not entry.lan,
expires_in=max(0, int(entry.expires - time.time())),
)
class DeviceCreate(BaseModel):
title: str = ""
class DevicePublic(DeviceDef):
"""A device as the Devices tab lists it, with whether it is there."""
online: bool = False
#: The last request it made, since this instance started.
last_seen: datetime | None = None
class DevicesPublic(BaseModel):
"""The devices, and the address a device should be pointed at.
The address is the server's own, because the browser's origin is not a
reliable answer: an admin working through the portal is on the portal's
origin, and this one is for a screen on this network.
"""
data: list[DevicePublic] = Field(default_factory=list)
count: int = 0
#: Whatever this instance was told it is reachable at, the setting the
#: password-reset links are built from too.
frontend_host: str = ""
def _describe(request: Request) -> str:
"""A line naming the device behind a pairing request.
# ponytail: the raw user agent, trimmed. Parse it into "iPad · Safari" if
# it reads badly on the approval screen.
"""
agent = request.headers.get("user-agent", "").strip()[:120]
# Resolved from X-Forwarded-For by the proxy-headers middleware, which is
# what makes a call replayed off the tunnel show the device's address and
# stops a device naming any address it likes.
address = request.client.host if request.client else ""
return " · ".join(part for part in (agent or "Unknown device", address) if part)
def _mint_at_hub(device_id: str) -> str:
"""Ask the portal for this device's credential.
A device that arrived through the portal cannot reach this instance, so a
token this instance signed would be one it could never present: the portal
verifies what crosses its tunnel against its own key. It mints, we say
which device, and the scope check here decides the rest.
"""
config = cloud_config.load()
if config is None:
raise HTTPException(
status_code=409,
detail="That device came through a portal this instance is no "
"longer enrolled with",
)
try:
response = httpx.post(
f"{config.portal_url.rstrip('/')}/api/v1/panel-tokens/",
headers={"Authorization": f"Bearer {config.token}"},
json={"panel": device_id},
timeout=15.0,
)
except httpx.HTTPError as exc:
raise HTTPException(
status_code=502, detail=f"Could not reach the portal: {exc}"
) from exc
if response.status_code != 200:
raise HTTPException(
status_code=502,
detail=f"The portal refused to mint a credential ({response.status_code})",
)
token: str = response.json()["access_token"]
return token
def _not_found(device_id: str) -> HTTPException:
return HTTPException(status_code=404, detail=f"No device named {device_id!r}")
def _changed() -> None:
"""Tell every device socket that what it shows may have moved.
An empty name says that much and no more: every screen listening rescopes
and refetches, which is also where an unpaired one meets its 401.
"""
event_bus.publish({"type": "dashboard_changed", "dashboard": "", "ts": time.time()})
# -- the device itself, before it holds anything -----------------------------
def start_pairing(request: Request, body: PairHello | None = None) -> Any:
"""A device asks to be adopted. Unauthenticated, by necessity.
All this hands out is a code that means nothing until somebody with an
account approves it, so the worst an unwelcome caller achieves is an entry
that expires ten minutes later. Reachable from the internet when this
instance is enrolled with a portal, which is what the cap and the portal's
own per-address limits are between.
"""
if _pending.count() >= MAX_PENDING:
raise HTTPException(
status_code=429, detail="Too many devices are waiting to be paired"
)
remote = cloud_config.via_portal(request.headers)
hello = body or PairHello()
entry = _Pending(
secret=secrets.token_urlsafe(16),
request=secrets.token_urlsafe(9),
expires=time.time() + PAIR_TTL,
device=_describe(request),
name=hello.name,
board=hello.board,
firmware=hello.firmware,
remote=remote,
lan=not remote and is_lan(request.client.host if request.client else ""),
)
# Claiming the code is what settles a collision, rather than looking
# first: between the look and the write sits another worker doing the same.
for _ in range(10):
code = "".join(secrets.choice(CODE_ALPHABET) for _ in range(CODE_LENGTH))
if _pending.add(code, entry):
break
else:
raise HTTPException(status_code=503, detail="Could not mint a pairing code")
return PairStarted(code=code, secret=entry.secret)
def poll_pairing(code: str, secret: str = "") -> Any:
"""Has anyone claimed this device yet?
Answers the same 404 for a code that never existed, one that expired and
one polled with the wrong secret: a caller reading a code off a wall learns
nothing by guessing.
"""
entry = _pending.get(code)
if entry is None or not secrets.compare_digest(entry.secret, secret):
raise HTTPException(
status_code=404, detail="No pairing is waiting on that code"
)
if not entry.token:
return PairStatus()
# Handed over once. A credential left lying in the store is a second copy
# of it, and the device has the only one it needs.
_pending.drop(code)
return PairStatus(
access_token=entry.token, device=entry.device_id, panel=entry.device_id
)
router.add_api_route(
"/pair", start_pairing, methods=["POST"], response_model=PairStarted
)
router.add_api_route(
"/pair/{code}", poll_pairing, methods=["GET"], response_model=PairStatus
)
panels_router.add_api_route(
"/pair", start_pairing, methods=["POST"], response_model=PairStarted
)
panels_router.add_api_route(
"/pair/{code}", poll_pairing, methods=["GET"], response_model=PairStatus
)
# -- people ------------------------------------------------------------------
@router.get("/", response_model=DevicesPublic, dependencies=[Depends(get_current_user)])
async def read_devices(store: DeviceStoreDep) -> Any:
"""Every device, what each one shows, and whether it is connected."""
devices = await run_in_threadpool(store.list)
data = [
DevicePublic(
**device.model_dump(),
online=presence.online(device.id),
last_seen=presence.last_seen(device.id),
)
for device in devices
]
return DevicesPublic(
data=data,
count=len(data),
frontend_host=settings.FRONTEND_HOST.rstrip("/"),
)
@router.get(
"/pending",
response_model=list[PendingDevice],
dependencies=[Depends(get_current_active_superuser)],
)
def read_pending() -> Any:
"""The devices asking for a code right now, as they describe themselves."""
waiting = sorted(_pending.waiting(), key=lambda item: -item[1].expires)
return [_pending_public(entry) for _, entry in waiting]
@router.get(
"/pair/{code}/device",
response_model=PendingDevice,
dependencies=[Depends(get_current_active_superuser)],
)
def pending_device(code: str) -> Any:
"""What is waiting on this code, before anyone says what it is."""
entry = _pending.get(code.strip().upper())
if entry is None:
raise HTTPException(status_code=404, detail="No device is waiting on that code")
return _pending_public(entry)
@router.post(
"/{device_id}",
response_model=DeviceDef,
dependencies=[Depends(get_current_active_superuser)],
)
async def create_device(
device_id: str, store: DeviceStoreDep, body: DeviceCreate | None = None
) -> Any:
"""Add a device. It shows nothing until it is given dashboards."""
if device_id in RESERVED:
raise HTTPException(status_code=422, detail=f"{device_id!r} is reserved")
try:
device = DeviceDef(id=device_id, title=(body.title if body else "").strip())
except ValueError as exc:
raise HTTPException(status_code=422, detail=str(exc))
try:
return await run_in_threadpool(store.create, device)
except DeviceExists:
raise HTTPException(status_code=409, detail=f"{device_id!r} already exists")
@router.get(
"/{device_id}",
response_model=DeviceDef,
dependencies=[Depends(get_current_user)],
)
async def read_device(device_id: str, store: DeviceStoreDep) -> Any:
"""One device, read by a person or by the device holding its credential.
The definition alone: a device compares what it reads with what it is
showing, and a field that changes on every request would rebuild its
screen each time. Declared after the pairing routes and ``/pending``, so
neither is mistaken for a device of that name.
"""
device = await run_in_threadpool(store.find, device_id)
if device is None:
raise _not_found(device_id)
return device
panels_router.add_api_route(
"/{device_id}",
read_device,
methods=["GET"],
response_model=DeviceDef,
dependencies=[Depends(get_current_user)],
)
@router.put(
"/{device_id}",
response_model=DeviceDef,
dependencies=[Depends(get_current_active_superuser)],
)
async def save_device(device_id: str, body: DeviceDef, store: DeviceStoreDep) -> Any:
"""Save a device. Takes effect on its next read.
The body carries the ``version`` it was based on, and a save someone else
has moved past is refused with 409.
"""
if body.id != device_id:
raise HTTPException(status_code=422, detail="The id in the body must match")
try:
saved = await run_in_threadpool(store.write, body, body.version)
except DeviceNotFound:
raise _not_found(device_id)
except StaleVersion as exc:
raise HTTPException(
status_code=409,
detail={
"message": "Someone else saved this device first",
"current_version": exc.current,
},
)
_changed()
return saved
@router.delete(
"/{device_id}",
response_model=Message,
dependencies=[Depends(get_current_active_superuser)],
)
async def delete_device(device_id: str, store: DeviceStoreDep) -> Any:
"""Remove the device and refuse its credential, wherever it was minted here."""
try:
await run_in_threadpool(store.delete, device_id)
except DeviceNotFound:
raise _not_found(device_id)
_changed()
return Message(message=f"Deleted {device_id}")
def _adopt(
code: str, entry: _Pending, device_id: str, user: User, store: DeviceStore
) -> str:
"""Mint the credential the device behind ``entry`` collects on its next poll.
One minted here names the approver, so what the device does stays
attributable to a person. One minted by the portal names the account this
instance was enrolled with instead.
"""
if entry.remote:
entry.token = _mint_at_hub(device_id)
else:
entry.token = security.create_panel_token(
device_id, user.id, timedelta(days=TOKEN_DAYS), store.nonce(device_id)
)
entry.device_id = device_id
_pending.save(code, entry)
return f"Paired {entry.name or entry.device} with {device_id}"
@router.post(
"/{device_id}/pair",
response_model=Message,
dependencies=[Depends(get_current_active_superuser)],
)
def approve_pairing(
device_id: str, body: PairRequest, current_user: CurrentUser, store: DeviceStoreDep
) -> Any:
"""Say which device the one showing this code, or making this request, is."""
if store.find(device_id) is None:
raise _not_found(device_id)
if body.code.strip():
code = body.code.strip().upper()
entry = _pending.get(code)
if entry is None:
raise HTTPException(
status_code=404,
detail="No device is waiting on that code. Check it again.",
)
elif body.request:
match = next(
(
(c, e)
for c, e in _pending.waiting()
if secrets.compare_digest(e.request, body.request)
),
None,
)
if match is None:
raise HTTPException(
status_code=404, detail="That device is no longer waiting"
)
code, entry = match
if not entry.lan:
raise HTTPException(
status_code=403,
detail="This request did not come from your network. Enter the "
"code the device shows instead.",
)
else:
raise HTTPException(status_code=422, detail="Send a code or a request")
return Message(message=_adopt(code, entry, device_id, current_user, store))
@router.post(
"/{device_id}/unpair",
response_model=Message,
dependencies=[Depends(get_current_active_superuser)],
)
async def unpair_device(device_id: str, store: DeviceStoreDep) -> Any:
"""Stop honouring this device's credential, and keep the device.
The screen hanging there is refused on its next request and goes back to
showing a pairing code, while its dashboards and their arrangement stay.
A credential the portal minted for a remote screen carries no nonce, so
this does not reach it. That one is revoked at the hub.
"""
if await run_in_threadpool(store.find, device_id) is None:
raise _not_found(device_id)
await run_in_threadpool(store.bump, device_id)
# The screen is still holding a socket. One event and it refetches, which
# is where it meets the 401 that sends it back to the pairing code.
_changed()
return Message(message=f"Unpaired {device_id}")
+30 -15
View File
@@ -36,9 +36,9 @@ from fluksio.core.db import engine
from fluksio.flow.artifacts import is_reference
from fluksio.flow.controller import NODE_TYPES, FlowController, follow_header
from fluksio.flow.dashboards import DashboardStore
from fluksio.flow.devices import DeviceStore, messages_for, presence
from fluksio.flow.events import event_bus
from fluksio.flow.messages import flow_of, qualify
from fluksio.flow.panels import messages_for, read_config
from fluksio.flow.pipeline import ValidationIssue
from fluksio.flow.runs import RunRejected
from fluksio.flow.schemas import (
@@ -157,22 +157,23 @@ def _endpoints(controller: FlowController, definition: FlowDef) -> list[Endpoint
requires=binding["requires"],
)
# A panel's own hardware: an ``in`` port publishes like a control, an
# A device's own hardware: an ``in`` port publishes like a control, an
# ``out`` port reads like a tile. The id is the source id the device
# publishes under, so its edges pulse for its values.
prefix = f"{flow}."
for panel in read_config().panels:
for port in panel.io:
devices: DeviceStore | None = getattr(controller, "devices", None)
for device in devices.list() if devices is not None else []:
for port in device.io:
if not port.message.startswith(prefix):
continue
key = f"panel:{panel.id}:{port.port}"
key = f"panel:{device.id}:{port.port}"
endpoint = found.setdefault(
key,
Endpoint(
kind="panel",
id=key,
label=port.port,
detail=panel.title or panel.id,
detail=device.title or device.id,
),
)
side = endpoint.provides if port.direction == "in" else endpoint.requires
@@ -1079,21 +1080,29 @@ def snapshot_payload(
}
def device_of(token: str, app: Any) -> str:
"""The device this credential stands for, or "" for a person or none."""
try:
return str(decode_token(token, app=app).get("panel") or "")
except InvalidTokenError:
return ""
def panel_scope(token: str, app: Any) -> set[str] | None:
"""The messages this credential is bounded to, or None if it is a person's.
The socket is the one authenticated surface the route check cannot reach —
a handshake has no route to judge — so a panel is bounded by what it is
The socket is the one authenticated surface the route check cannot reach,
a handshake has no route to judge, so a device is bounded by what it is
sent instead of by what it asks for.
"""
try:
panel = str(decode_token(token).get("panel") or "")
except InvalidTokenError:
return None
if not panel:
device_id = device_of(token, app)
if not device_id:
return None
store: DashboardStore | None = getattr(app.state, "dashboard_store", None)
return messages_for(panel, store) if store is not None else set()
devices: DeviceStore | None = getattr(app.state, "device_store", None)
if store is None or devices is None:
return set()
return messages_for(devices.find(device_id), store)
def event_for_panel(event: dict[str, Any], only: set[str]) -> bool:
@@ -1236,13 +1245,15 @@ async def flow_events(websocket: WebSocket, ticket: str = "", token: str = "") -
# every other socket and every request is sharing.
def _authenticate() -> Any:
with Session(engine) as session:
return user_from_token(session, token)
return user_from_token(session, token, app=websocket.app)
user = await run_in_threadpool(_authenticate)
if user is None:
await websocket.close(code=1008)
return
only = panel_scope(token, websocket.app)
# A device is online for as long as this socket is open.
device = device_of(token, websocket.app) if only is not None else ""
# Nothing until a client says it is drawing something: bytes are what this
# socket cannot afford to send speculatively.
wanted: set[str] = set()
@@ -1263,6 +1274,8 @@ async def flow_events(websocket: WebSocket, ticket: str = "", token: str = "") -
async with event_bus.subscribe() as queue:
receiver = asyncio.create_task(websocket.receive_text())
if device:
presence.opened(device)
try:
while True:
sender = asyncio.create_task(queue.get())
@@ -1337,3 +1350,5 @@ async def flow_events(websocket: WebSocket, ticket: str = "", token: str = "") -
pass
finally:
receiver.cancel()
if device:
presence.closed(device)
-507
View File
@@ -1,507 +0,0 @@
"""Panels: which dashboards a device shows, and how it gets a credential.
A wall tablet has no keyboard, so it cannot log in. It asks for a code instead,
shows it on the wall, and somebody with an account types that code into the
panels dialog to say which panel the device is. The device polls, collects the
credential the approval minted, and never asks again.
A screen hanging somewhere this instance is not reachable from does the
same thing through the portal, which forwards those two calls down the tunnel
without a session — a device with no credential is the whole point of them —
and mints the credential itself when the approval comes. Which side minted it
changes nothing about what it may do: the scope check is here either way.
The credential is scoped: ``fluksio.api.deps`` lets it reach the dashboards that
panel was assigned, the messages their widgets bind to, and nothing else.
Removing the panel revokes it; so does bumping the panel's nonce, which is how
one screen is re-paired without disturbing what it was showing.
"""
from __future__ import annotations
import secrets
import time
from datetime import timedelta
from typing import Any, cast
import httpx
import redis
from fastapi import APIRouter, Depends, HTTPException, Request
from fastapi.concurrency import run_in_threadpool
from pydantic import BaseModel, Field
from fluksio.api.deps import CurrentUser, get_current_active_superuser, get_current_user
from fluksio.cloud import config as cloud_config
from fluksio.core import security
from fluksio.core.config import settings
from fluksio.flow.events import event_bus
from fluksio.flow.panels import (
PanelDef,
PanelsConfig,
edit_lock,
find,
read_config,
write_config,
)
from fluksio.flow.state import CONNECT_TIMEOUT_S, SOCKET_TIMEOUT_S
from fluksio.models import Message
#: Gated per route rather than on the router: the two pairing endpoints are the
#: only unauthenticated ones in the app, because a device with no credential is
#: the whole point of them.
router = APIRouter(prefix="/panels", tags=["panels"])
#: Long, because a panel is a screen somebody hung once and left running, with
#: no keyboard to sign in again with. Same reasoning as a remote worker's.
TOKEN_DAYS = 365
#: How long a device's code is worth typing. Long enough to walk to a computer.
PAIR_TTL = 600
#: No I/O/0/1: the code is read off a wall and typed on a keyboard.
CODE_ALPHABET = "ABCDEFGHJKLMNPQRSTUVWXYZ23456789"
CODE_LENGTH = 6
#: Refuse to grow past this. Codes are free to ask for and cost memory.
MAX_PENDING = 50
class _Pending(BaseModel):
"""A device waiting to be told what it is."""
#: Held by the device, never shown.
secret: str
#: Wall-clock rather than monotonic: an entry outlives the process that
#: minted it, and monotonic clocks are not comparable across processes.
expires: float
token: str = ""
panel: str = ""
#: What the request looked like, shown to whoever approves the code so
#: they can tell the screen in the hall from one they were not expecting.
#: Self-reported and worth what that is worth.
device: str = ""
#: Whether it came down the tunnel. A device that reached the portal
#: cannot reach this instance, so its credential has to be minted
#: where it can collect it.
remote: bool = False
#: The entry itself, one key per code, expiring on its own.
_PENDING_KEY = "panels:pair"
#: An index of the live codes, so :data:`MAX_PENDING` means the same thing to
#: every worker. Scored by expiry, which is how it is pruned.
_PENDING_INDEX = "panels:pair:__codes__"
class _PendingStore:
"""The codes waiting for somebody to say what they are.
A device's poll lands on whichever API worker the proxy picked, and a
screen pairing through the portal lands on whichever one holds the tunnel
— so a code minted by one worker has to be findable from the next. Redis
is where this instance already keeps what must outlive a process.
Without one there is one process by definition (the pip install, and the
tests), and a dictionary is the same thing for it.
"""
def __init__(self) -> None:
self._local: dict[str, _Pending] = {}
self._redis: redis.Redis | None = (
redis.Redis(
host=settings.REDIS_HOST,
port=settings.REDIS_PORT,
decode_responses=True,
# A silent Redis must fail this request, not hold it open.
socket_timeout=SOCKET_TIMEOUT_S,
socket_connect_timeout=CONNECT_TIMEOUT_S,
health_check_interval=30,
)
if settings.REDIS_HOST
else None
)
def _key(self, code: str) -> str:
return f"{_PENDING_KEY}:{code}"
def count(self) -> int:
"""How many are waiting, the expired ones dropped first."""
now = time.time()
if self._redis is None:
for code in [c for c, e in self._local.items() if e.expires < now]:
del self._local[code]
return len(self._local)
self._redis.zremrangebyscore(_PENDING_INDEX, "-inf", now)
return int(cast(int, self._redis.zcard(_PENDING_INDEX)))
def add(self, code: str, entry: _Pending) -> bool:
"""Claim this code, or say that somebody already holds it."""
if self._redis is None:
if code in self._local:
return False
self._local[code] = entry
return True
if not self._redis.set(
self._key(code), entry.model_dump_json(), ex=PAIR_TTL, nx=True
):
return False
self._redis.zadd(_PENDING_INDEX, {code: entry.expires})
return True
def get(self, code: str) -> _Pending | None:
if self._redis is None:
entry = self._local.get(code)
else:
raw = cast("str | None", self._redis.get(self._key(code)))
entry = _Pending.model_validate_json(raw) if raw else None
return entry if entry is not None and entry.expires >= time.time() else None
def save(self, code: str, entry: _Pending) -> None:
"""Write an approval back, without moving what it expires at."""
if self._redis is None:
self._local[code] = entry
return
self._redis.set(
self._key(code),
entry.model_dump_json(),
ex=max(1, int(entry.expires - time.time())),
)
def drop(self, code: str) -> None:
if self._redis is None:
self._local.pop(code, None)
return
self._redis.delete(self._key(code))
self._redis.zrem(_PENDING_INDEX, code)
_pending = _PendingStore()
class PairStarted(BaseModel):
"""What the device puts on the wall, and what it polls with."""
code: str
#: Held by the device, never shown. Without it the code alone would let
#: anyone who reads it off the wall collect the credential first.
secret: str
expires_in: int = PAIR_TTL
class PairStatus(BaseModel):
"""Nothing yet, or the credential and the panel it is for."""
access_token: str | None = None
panel: str | None = None
class PairRequest(BaseModel):
code: str
class PendingDevice(BaseModel):
"""Who is asking, as far as the request itself says."""
device: str
remote: bool = False
def _describe(request: Request) -> str:
"""A line naming the device behind a pairing request.
# ponytail: the raw user agent, trimmed. Parse it into "iPad · Safari" if
# it reads badly on the approval screen.
"""
agent = request.headers.get("user-agent", "").strip()[:120]
# Resolved from X-Forwarded-For by the proxy-headers middleware, which is
# what makes a call replayed off the tunnel show the device's address
# rather than localhost — and stops a device naming any address it likes.
address = request.client.host if request.client else ""
return " · ".join(part for part in (agent or "Unknown device", address) if part)
def _mint_at_hub(panel_id: str) -> str:
"""Ask the portal for this panel's credential.
A device that arrived through the portal cannot reach this instance, so
a token this instance signed would be one it could never present: the
portal verifies what crosses its tunnel, and it verifies against its own
key. It mints, we say which panel — and the scope check here decides the
rest, on this call and on every later one.
"""
config = cloud_config.load()
if config is None:
raise HTTPException(
status_code=409,
detail="That device came through a portal this instance is no "
"longer enrolled with",
)
try:
response = httpx.post(
f"{config.portal_url.rstrip('/')}/api/v1/panel-tokens/",
headers={"Authorization": f"Bearer {config.token}"},
json={"panel": panel_id},
timeout=15.0,
)
except httpx.HTTPError as exc:
raise HTTPException(
status_code=502, detail=f"Could not reach the portal: {exc}"
) from exc
if response.status_code != 200:
raise HTTPException(
status_code=502,
detail=f"The portal refused to mint a credential ({response.status_code})",
)
token: str = response.json()["access_token"]
return token
class PanelsPublic(BaseModel):
"""The panels, and the address a device should be pointed at.
The address is the server's own, because the browser's origin is not a
reliable answer to it: an admin working through the portal is on the
portal's origin, and this one is for a screen on this network.
An instance enrolled with a portal has a second address, built by the
dialog from what ``/cloud/status`` reports rather than from here — a panel
is not the thing that knows whether remote access is on.
"""
panels: list[PanelDef] = Field(default_factory=list)
#: What a save of this list has to send back.
version: int = 0
#: Whatever this instance was told it is reachable at. The same setting
#: the password-reset links are built from, so an instance that has it
#: wrong has it wrong in both places.
frontend_host: str = ""
def _public(config: PanelsConfig) -> PanelsPublic:
return PanelsPublic(
panels=config.panels,
version=config.version,
frontend_host=settings.FRONTEND_HOST.rstrip("/"),
)
@router.get("/", response_model=PanelsPublic, dependencies=[Depends(get_current_user)])
async def read_panels() -> Any:
"""Every panel, what each one shows, and where to point a device."""
return _public(await run_in_threadpool(read_config))
@router.put(
"/",
response_model=PanelsPublic,
dependencies=[Depends(get_current_active_superuser)],
)
async def save_panels(body: PanelsConfig) -> Any:
"""Replace the panels. Takes effect on the devices' next read.
A panel that disappears here takes its credential with it, so this is also
how a device is unpaired along with its assignment. Re-pairing one screen
and keeping the assignment is ``/{panel_id}/unpair`` below.
The body carries the ``version`` it was based on, and a save someone else
has moved past is refused with 409, as a dashboard's is. Two clients each
writing back the whole list would otherwise drop each other's panels, and
a dropped panel revokes its screen at once.
"""
seen = set()
for panel in body.panels:
if panel.id in seen:
raise HTTPException(
status_code=422, detail=f"Two panels named {panel.id!r}"
)
seen.add(panel.id)
def _save() -> None:
# Read and write under one lock. The nonce belongs to this
# instance, not to whoever is writing the panels back: a client
# holding an older copy must not be able to undo a revocation by
# saving an arrangement — and reading it in a separate step from
# writing it is exactly how an unpair in between was undone.
with edit_lock:
stored = read_config()
if body.version != stored.version:
raise HTTPException(
status_code=409,
detail={
"message": "Someone else saved the panels first",
"current_version": stored.version,
},
)
nonces = {p.id: p.nonce for p in stored.panels}
for panel in body.panels:
panel.nonce = nonces.get(panel.id, 0)
body.version = stored.version + 1
write_config(body)
await run_in_threadpool(_save)
# Which dashboards hang on which panel just changed. An empty name says
# that much and no more: every screen listening rescopes and refetches
# what it shows, rather than waiting for whenever it next reads.
event_bus.publish({"type": "dashboard_changed", "dashboard": "", "ts": time.time()})
return _public(body)
@router.post("/pair", response_model=PairStarted)
def start_pairing(request: Request) -> Any:
"""A device asks to be adopted. Unauthenticated, by necessity.
All this hands out is a code that means nothing until somebody with an
account approves it, so the worst an unwelcome caller achieves is an entry
that expires ten minutes later. Reachable from the internet when this
instance is enrolled with a portal, which is what the cap and the
portal's own per-address limits are between.
"""
if _pending.count() >= MAX_PENDING:
raise HTTPException(
status_code=429, detail="Too many devices are waiting to be paired"
)
remote = secrets.compare_digest(
request.headers.get(cloud_config.VIA_HEADER, ""), cloud_config.VIA_PORTAL
)
entry = _Pending(
secret=secrets.token_urlsafe(16),
expires=time.time() + PAIR_TTL,
device=_describe(request),
remote=remote,
)
# Claiming the code is what settles a collision, rather than looking first:
# between the look and the write sits another worker doing the same thing.
for _ in range(10):
code = "".join(secrets.choice(CODE_ALPHABET) for _ in range(CODE_LENGTH))
if _pending.add(code, entry):
break
else:
raise HTTPException(status_code=503, detail="Could not mint a pairing code")
return PairStarted(code=code, secret=entry.secret)
@router.get("/pair/{code}", response_model=PairStatus)
def poll_pairing(code: str, secret: str = "") -> Any:
"""Has anyone claimed this device yet?
Answers the same 404 for a code that never existed, one that expired and
one polled with the wrong secret: a caller reading a code off a wall learns
nothing by guessing.
"""
entry = _pending.get(code)
if entry is None or not secrets.compare_digest(entry.secret, secret):
raise HTTPException(
status_code=404, detail="No pairing is waiting on that code"
)
if not entry.token:
return PairStatus()
# Handed over once. A credential left lying in the store is a second copy
# of it, and the device has the only one it needs.
_pending.drop(code)
return PairStatus(access_token=entry.token, panel=entry.panel)
@router.get(
"/pair/{code}/device",
response_model=PendingDevice,
dependencies=[Depends(get_current_active_superuser)],
)
def pending_device(code: str) -> Any:
"""What is waiting on this code, before anyone says what it is.
Approving a code adopts whatever is holding it, so it is worth seeing that
it looks like the screen you just hung.
"""
entry = _pending.get(code.strip().upper())
if entry is None:
raise HTTPException(status_code=404, detail="No device is waiting on that code")
return PendingDevice(device=entry.device, remote=entry.remote)
@router.post(
"/{panel_id}/pair",
response_model=Message,
dependencies=[Depends(get_current_active_superuser)],
)
def approve_pairing(panel_id: str, body: PairRequest, current_user: CurrentUser) -> Any:
"""Say which panel the device showing this code is.
A credential minted here names the approver, so what the panel does stays
attributable to a person rather than to nobody. One minted by the portal —
for a device that reached this instance only through it — names the
account this instance was enrolled with instead, since that is the one
every portal-borne request already acts as.
"""
panel = find(panel_id)
if panel is None:
raise HTTPException(status_code=404, detail=f"No panel named {panel_id!r}")
code = body.code.strip().upper()
entry = _pending.get(code)
if entry is None:
raise HTTPException(
status_code=404,
detail="No device is waiting on that code — check it again",
)
if entry.remote:
entry.token = _mint_at_hub(panel_id)
else:
entry.token = security.create_panel_token(
panel_id, current_user.id, timedelta(days=TOKEN_DAYS), panel.nonce
)
entry.panel = panel_id
_pending.save(code, entry)
return Message(message=f"Paired {entry.device} with {panel_id}")
@router.post(
"/{panel_id}/unpair",
response_model=Message,
dependencies=[Depends(get_current_active_superuser)],
)
async def unpair_panel(panel_id: str) -> Any:
"""Stop honouring this panel's credential, and keep the panel.
Bumping the nonce refuses the screen hanging there on its next request, so
it goes back to showing a pairing code — while the panel, the dashboards it
was assigned and their arrangement stay exactly as they were. Deleting the
panel is still what throws all three away together.
A credential the portal minted for a remote screen carries no nonce, so
this does not reach it; that one is revoked at the hub.
"""
def _unpair() -> bool:
with edit_lock:
config = read_config()
panel = next((p for p in config.panels if p.id == panel_id), None)
if panel is None:
return False
panel.nonce += 1
write_config(config)
return True
if not await run_in_threadpool(_unpair):
raise HTTPException(status_code=404, detail=f"No panel named {panel_id!r}")
# The screen is still holding a socket. One event and it refetches, which
# is where it meets the 401 that sends it back to the pairing code.
event_bus.publish({"type": "dashboard_changed", "dashboard": "", "ts": time.time()})
return Message(message=f"Unpaired {panel_id}")
@router.get(
"/{panel_id}", response_model=PanelDef, dependencies=[Depends(get_current_user)]
)
async def read_panel(panel_id: str) -> Any:
"""One panel — read by a person, or by the device holding its credential.
Declared after the pairing routes so a device polling ``/panels/pair/...``
is never mistaken for someone reading a panel named ``pair``.
"""
panel = await run_in_threadpool(find, panel_id)
if panel is None:
raise HTTPException(status_code=404, detail=f"No panel named {panel_id!r}")
return panel
+6 -5
View File
@@ -13,14 +13,14 @@ from fluksio.api.deps import (
get_current_user,
)
from fluksio.api.routes.alerts import read_config as read_alerts_config
from fluksio.flow import modules, panels
from fluksio.flow import modules
from fluksio.flow.controller import FlowController
from fluksio.flow.dashboards import DashboardNotFound, DashboardStore
from fluksio.flow.messages import qualify
from fluksio.flow.secrets import get_secrets
from fluksio.flow.store import FlowNotFound
# A wall panel never reaches this route: ``deps._panel_may`` is a whitelist that
# A device never reaches this route: ``deps._device_may`` is a whitelist that
# ends in a 403, and a whole-instance index is the opposite of what a screen
# on a wall is allowed to read.
router = APIRouter(
@@ -34,7 +34,7 @@ Category = Literal[
"output",
"dashboard",
"widget",
"panel",
"device",
"secret",
"module",
"worker",
@@ -132,9 +132,10 @@ def _build(
for widget in dashboard.widgets
)
devices = getattr(controller, "devices", None)
entries.extend(
SearchEntry(category="panel", name=panel.id, title=panel.title)
for panel in panels.read_config().panels
SearchEntry(category="device", name=device.id, title=device.title)
for device in (devices.list() if devices is not None else [])
)
if secrets: