feat(devices): pairing-UX scaffold (Phase 2)
Lays the groundwork for device families that require a one-time
physical pairing action (Nanoleaf hold-power-button, Tuya local-key
extraction, Twinkly network-setup mode, Hue link-button). No driver
uses it yet -- Nanoleaf will be the first concrete consumer.
Phase 2 as originally written had three bullets; only this one was
genuinely missing work. The other two (generic NetworkDiscoveryService
fan-out, unified scan-network UI) were already solved at the route
level by the existing /api/v1/devices/discover handler running all
providers in parallel via asyncio.gather(return_exceptions=True).
Marked WONTDO in TODO.md with rationale.
Backend:
- LEDDeviceProvider gains an async pair_device(url) -> dict method.
Default raises NotImplementedError so missing implementations on a
requires_pairing provider fail loud at request time.
- New PairingNotReady exception, distinct from generic errors so the
route handler can return 409 (user must perform the physical action,
retry possible) instead of 500.
- POST /api/v1/devices/pair endpoint with PairDeviceRequest /
PairDeviceResponse schemas. Status-code mapping:
200 -> paired, fields returned for the subsequent create payload
400 -> unknown device type, or type doesn't support pairing
409 -> PairingNotReady (retryable from the UI)
422 -> invalid URL / device configuration (ValueError)
502 -> transport / network failure (other exceptions)
500 -> provider returned a non-dict (defensive)
- 8 route tests register a stub provider and exercise every
status-code path.
Frontend:
- New modals/pair-device.html with five state blocks (idle / pairing
/ not_ready / success / failed) toggled via data-pair-state, plus
a 30-second SVG progress ring with monospace countdown.
- New features/pairing-flow.ts exposing
runPairingFlow({deviceType, url, instructionsKey?}) ->
Promise<{fields: Record<string, unknown>>. Wires the modal to the
pair endpoint, maps response codes to UI states, AbortControllers
in-flight fetches on cancel. Exports a PairingCancelled sentinel
error class.
- Generic pairing.* i18n keys in en/ru/zh. Drivers will add their own
device.<type>.pair.instructions key that overrides the default.
Design decisions (per frontend-design skill):
- Single SVG ring + centered countdown (HomeKit-style)
- Instructions stay visible during pairing, dimmed to 60% via :has()
- Success state held 450 ms before auto-dismiss
- Cancel-X in the footer; primary action lives in the state block
- prefers-reduced-motion disables pulse/fade/ring transitions
Note: the components.css diff includes a pre-existing MiniSelect block
from the user's parallel work; pairing-specific styles are the second
hunk (lines ~1628+).
This commit is contained in:
@@ -710,9 +710,24 @@ Philips' UDP-local budget tier. Port 38899 JSON UDP.
|
||||
|
||||
After phase 1 the codebase will have 3 fresh examples of "ping the LAN, listen for replies, present a list". Factor that out into a generic discovery scaffold + a "first-run pairing" UX component before adding Tuya/Govee/etc., which each need a one-time pairing dance.
|
||||
|
||||
- [ ] Generic `NetworkDiscoveryService` that fan-outs mDNS + SSDP + UDP-broadcast probes in parallel
|
||||
- [ ] Unified "scan network for devices" UI affordance instead of per-type buttons
|
||||
- [ ] Reusable "pair device" component (consent button, countdown, retry)
|
||||
- [WONTDO] Generic `NetworkDiscoveryService` — the existing
|
||||
`/api/v1/devices/discover` route already runs all providers in parallel
|
||||
via `asyncio.gather(return_exceptions=True)`. Extracting it would not
|
||||
unlock anything; revisit only if discovery cadence/dedup becomes a
|
||||
real complaint.
|
||||
- [WONTDO] Unified scan UI — already exists; one "Scan network" button
|
||||
triggers the cross-provider fan-out.
|
||||
- [x] **Reusable pair-device scaffold** (the actually-needed piece).
|
||||
Backend: `LEDDeviceProvider.pair_device(url)` abstract method with
|
||||
`PairingNotReady` sentinel; `POST /api/v1/devices/pair` endpoint
|
||||
with status-code mapping (200/400/409/422/502); 8 route tests
|
||||
covering every outcome. Frontend: `templates/modals/pair-device.html`
|
||||
five-state modal (idle / pairing / not-ready / success / failed)
|
||||
with a 30-second SVG progress ring; reusable
|
||||
`static/js/features/pairing-flow.ts` exposing
|
||||
`runPairingFlow({deviceType, url}) → Promise<{fields}>` with
|
||||
`PairingCancelled` sentinel; locale strings in en/ru/zh. No driver
|
||||
uses it yet — Nanoleaf will be the first concrete consumer.
|
||||
|
||||
### Phase 3 — Big aggregator unlocks
|
||||
|
||||
|
||||
@@ -5,6 +5,7 @@ from fastapi import APIRouter, HTTPException, Depends, Query, WebSocket, WebSock
|
||||
|
||||
from ledgrab.api.auth import AuthRequired
|
||||
from ledgrab.core.devices.led_client import (
|
||||
PairingNotReady,
|
||||
get_all_providers,
|
||||
get_device_capabilities,
|
||||
get_provider,
|
||||
@@ -26,6 +27,8 @@ from ledgrab.api.schemas.devices import (
|
||||
DiscoverDevicesResponse,
|
||||
OpenRGBZoneResponse,
|
||||
OpenRGBZonesResponse,
|
||||
PairDeviceRequest,
|
||||
PairDeviceResponse,
|
||||
PowerRequest,
|
||||
)
|
||||
from ledgrab.core.processing.processor_manager import ProcessorManager
|
||||
@@ -282,6 +285,72 @@ async def create_device(
|
||||
raise HTTPException(status_code=500, detail="Internal server error")
|
||||
|
||||
|
||||
@router.post(
|
||||
"/api/v1/devices/pair",
|
||||
response_model=PairDeviceResponse,
|
||||
tags=["Devices"],
|
||||
)
|
||||
async def pair_device(
|
||||
body: PairDeviceRequest,
|
||||
_auth: AuthRequired,
|
||||
):
|
||||
"""Run a pairing handshake against a device before creating it.
|
||||
|
||||
The frontend opens this endpoint after the user has performed the
|
||||
device's physical pairing action (e.g. held the power button for 5s).
|
||||
The response carries provider-specific fields the caller must include
|
||||
in the subsequent ``POST /api/v1/devices`` body.
|
||||
|
||||
Status codes:
|
||||
200 paired — fields returned
|
||||
400 unknown device type, or device type does not support pairing
|
||||
409 device not ready — user must perform the physical action
|
||||
(or retry, e.g. the pairing window timed out)
|
||||
422 invalid URL or device configuration
|
||||
"""
|
||||
try:
|
||||
provider = get_provider(body.device_type)
|
||||
except ValueError:
|
||||
raise HTTPException(status_code=400, detail=f"Unknown device type: {body.device_type}")
|
||||
|
||||
try:
|
||||
fields = await provider.pair_device(body.url)
|
||||
except NotImplementedError:
|
||||
raise HTTPException(
|
||||
status_code=400,
|
||||
detail=f"Device type {body.device_type!r} does not support pairing",
|
||||
)
|
||||
except PairingNotReady as exc:
|
||||
raise HTTPException(status_code=409, detail=str(exc))
|
||||
except ValueError as exc:
|
||||
raise HTTPException(status_code=422, detail=str(exc))
|
||||
except Exception as exc:
|
||||
logger.warning(
|
||||
"Pairing failed for %s at %s: %s",
|
||||
body.device_type,
|
||||
body.url,
|
||||
exc,
|
||||
exc_info=True,
|
||||
)
|
||||
raise HTTPException(
|
||||
status_code=502,
|
||||
detail=f"Pairing failed for {body.device_type} at {body.url}.",
|
||||
)
|
||||
|
||||
if not isinstance(fields, dict):
|
||||
logger.warning(
|
||||
"Provider %s.pair_device returned %r (expected dict)",
|
||||
body.device_type,
|
||||
type(fields).__name__,
|
||||
)
|
||||
raise HTTPException(
|
||||
status_code=500,
|
||||
detail=f"Provider {body.device_type!r} returned malformed pairing result",
|
||||
)
|
||||
|
||||
return PairDeviceResponse(fields=fields)
|
||||
|
||||
|
||||
@router.get("/api/v1/devices", response_model=DeviceListResponse, tags=["Devices"])
|
||||
async def list_devices(
|
||||
_auth: AuthRequired,
|
||||
|
||||
@@ -232,6 +232,32 @@ class DeviceUpdate(BaseModel):
|
||||
)
|
||||
|
||||
|
||||
class PairDeviceRequest(BaseModel):
|
||||
"""Initiate a pairing handshake with a device before creating it.
|
||||
|
||||
The caller is expected to have just performed the device's physical
|
||||
pairing action (e.g. holding the power button on a Nanoleaf for 5 s,
|
||||
pressing the Hue bridge link button). The response carries any
|
||||
provider-specific fields the frontend must include in the subsequent
|
||||
``POST /api/v1/devices`` payload — typically an auth token.
|
||||
"""
|
||||
|
||||
device_type: str = Field(description="Device type identifier (e.g. 'nanoleaf')")
|
||||
url: str = Field(description="Device URL (e.g. 'nanoleaf://192.168.1.50')")
|
||||
|
||||
|
||||
class PairDeviceResponse(BaseModel):
|
||||
"""Successful pairing result. ``fields`` is merged into the create payload."""
|
||||
|
||||
fields: Dict[str, object] = Field(
|
||||
default_factory=dict,
|
||||
description=(
|
||||
"Provider-specific fields to include in the subsequent device-create "
|
||||
"request (e.g. {'nanoleaf_token': 'abc...'})."
|
||||
),
|
||||
)
|
||||
|
||||
|
||||
class CalibrationLineSchema(BaseModel):
|
||||
"""One LED line in advanced calibration."""
|
||||
|
||||
|
||||
@@ -37,6 +37,15 @@ class DeviceHealth:
|
||||
error: Optional[str] = None
|
||||
|
||||
|
||||
class PairingNotReady(Exception):
|
||||
"""Raised by ``pair_device`` when the user hasn't performed the physical
|
||||
pairing action yet (or it timed out before the device acknowledged).
|
||||
|
||||
Distinct from generic exceptions so the route handler can return a 409
|
||||
instead of a 500 — the UI shows a retry prompt rather than a hard error.
|
||||
"""
|
||||
|
||||
|
||||
@dataclass
|
||||
class DiscoveredDevice:
|
||||
"""A device found via network discovery."""
|
||||
@@ -216,6 +225,30 @@ class LEDDeviceProvider(ABC):
|
||||
"""
|
||||
return []
|
||||
|
||||
async def pair_device(self, url: str) -> Dict[str, object]:
|
||||
"""Run a pairing handshake against the device at ``url``.
|
||||
|
||||
Implementations expect the user to have just performed the device's
|
||||
physical pairing action (Nanoleaf: hold power 5s; Hue: press the
|
||||
link button; Twinkly: enter Network setup mode) before calling.
|
||||
|
||||
Returns:
|
||||
A dict of provider-specific fields that the caller should merge
|
||||
into the subsequent ``create_device`` payload — e.g.
|
||||
``{"nanoleaf_token": "abc..."}`` or ``{"tuya_local_key": "..."}``.
|
||||
|
||||
Raises:
|
||||
PairingNotReady when the user hasn't performed the physical
|
||||
action yet (the caller surfaces this as a retryable 409 so
|
||||
the UI can show "Press the button now, then try again").
|
||||
ValueError on a fundamentally invalid URL or device.
|
||||
|
||||
Default: raises ``NotImplementedError`` so a missing implementation
|
||||
on a ``requires_pairing`` provider fails loud at request time
|
||||
rather than silently returning an empty dict.
|
||||
"""
|
||||
raise NotImplementedError(f"{self.device_type} doesn't support pairing")
|
||||
|
||||
async def get_brightness(self, url: str) -> int:
|
||||
"""Get device brightness (0-255). Override if capabilities include brightness_control."""
|
||||
raise NotImplementedError
|
||||
|
||||
@@ -1045,6 +1045,79 @@ textarea:focus-visible {
|
||||
border-color: var(--primary-color);
|
||||
background: color-mix(in srgb, var(--primary-color) 12%, var(--bg-secondary));
|
||||
}
|
||||
/* ── MiniSelect (icon-less compact dropdown) ── */
|
||||
.mini-select-trigger {
|
||||
display: inline-flex;
|
||||
align-items: center;
|
||||
gap: 6px;
|
||||
padding: 4px 10px;
|
||||
min-height: 28px;
|
||||
background: var(--bg-secondary);
|
||||
border: 1px solid var(--border-color);
|
||||
border-radius: 6px;
|
||||
color: var(--text-primary);
|
||||
font-size: 0.85rem;
|
||||
cursor: pointer;
|
||||
transition: border-color 120ms ease, background 120ms ease;
|
||||
}
|
||||
.mini-select-trigger:hover,
|
||||
.mini-select-trigger:focus-visible {
|
||||
border-color: var(--primary-color);
|
||||
}
|
||||
.mini-select-trigger-arrow {
|
||||
opacity: 0.6;
|
||||
font-size: 0.75em;
|
||||
}
|
||||
.mini-select-popup {
|
||||
position: fixed;
|
||||
background: var(--card-bg);
|
||||
border: 1px solid var(--border-color);
|
||||
border-radius: 8px;
|
||||
box-shadow: 0 6px 24px rgba(0, 0, 0, 0.35);
|
||||
z-index: 9999;
|
||||
overflow-y: auto;
|
||||
display: none;
|
||||
padding: 4px;
|
||||
min-width: 120px;
|
||||
}
|
||||
.mini-select-popup.open { display: block; }
|
||||
.mini-select-popup:focus,
|
||||
.mini-select-popup:focus-visible {
|
||||
outline: none;
|
||||
}
|
||||
.mini-select-option {
|
||||
padding: 6px 10px;
|
||||
border-radius: 4px;
|
||||
cursor: pointer;
|
||||
color: var(--text-primary);
|
||||
font-size: 0.85rem;
|
||||
user-select: none;
|
||||
}
|
||||
.mini-select-option:hover {
|
||||
background: color-mix(in srgb, var(--primary-color) 14%, transparent);
|
||||
}
|
||||
.mini-select-option.active {
|
||||
color: var(--primary-color);
|
||||
font-weight: 600;
|
||||
}
|
||||
.mini-select-option.focused {
|
||||
background: color-mix(in srgb, var(--primary-color) 20%, transparent);
|
||||
box-shadow: inset 0 0 0 2px color-mix(in srgb, var(--primary-color) 45%, transparent);
|
||||
}
|
||||
|
||||
.icon-select-cell.focused {
|
||||
border-color: var(--primary-color);
|
||||
box-shadow: 0 0 0 3px color-mix(in srgb, var(--primary-color) 30%, transparent);
|
||||
}
|
||||
/* When the keyboard cursor lands on the currently-selected cell, intensify
|
||||
the focus ring so the combined active+focused state is unambiguous. */
|
||||
.icon-select-cell.active.focused {
|
||||
box-shadow: 0 0 0 3px color-mix(in srgb, var(--primary-color) 55%, transparent);
|
||||
}
|
||||
.icon-select-popup:focus,
|
||||
.icon-select-popup:focus-visible {
|
||||
outline: none;
|
||||
}
|
||||
|
||||
.icon-select-cell-icon {
|
||||
display: flex;
|
||||
@@ -1628,3 +1701,194 @@ textarea:focus-visible {
|
||||
height: 16px;
|
||||
fill: currentColor;
|
||||
}
|
||||
|
||||
/* ── Pair Device Modal ──────────────────────────────────────────
|
||||
Reusable handshake UI for drivers that require a physical pairing
|
||||
action (Nanoleaf, Tuya, Twinkly, …). See `features/pairing-flow.ts`
|
||||
and `modals/pair-device.html`. The instructions stay visible across
|
||||
states, dimming during pairing so the user remains oriented while
|
||||
the progress ring takes focal point. */
|
||||
|
||||
.pair-instructions {
|
||||
color: var(--lux-ink-dim, var(--text-secondary));
|
||||
font-size: 0.92rem;
|
||||
line-height: 1.5;
|
||||
margin: 0 0 18px 0;
|
||||
transition: opacity 0.25s ease;
|
||||
}
|
||||
|
||||
.pair-states[data-pair-state="pairing"] ~ .pair-instructions,
|
||||
.pair-states[data-pair-state="pairing"] .pair-instructions {
|
||||
/* Selector kept for posterity — actual dimming is applied via the
|
||||
parent attribute below. */
|
||||
}
|
||||
|
||||
.modal-body:has(.pair-states[data-pair-state="pairing"]) .pair-instructions {
|
||||
opacity: 0.6;
|
||||
}
|
||||
|
||||
.pair-states {
|
||||
display: flex;
|
||||
flex-direction: column;
|
||||
align-items: center;
|
||||
justify-content: center;
|
||||
gap: 18px;
|
||||
padding: 8px 0 4px;
|
||||
min-height: 200px;
|
||||
}
|
||||
|
||||
.pair-state {
|
||||
display: flex;
|
||||
flex-direction: column;
|
||||
align-items: center;
|
||||
justify-content: center;
|
||||
gap: 18px;
|
||||
width: 100%;
|
||||
animation: pairFade 0.28s ease both;
|
||||
}
|
||||
|
||||
@keyframes pairFade {
|
||||
from { opacity: 0; transform: translateY(4px); }
|
||||
to { opacity: 1; transform: none; }
|
||||
}
|
||||
|
||||
.pair-action {
|
||||
min-width: 180px;
|
||||
justify-content: center;
|
||||
}
|
||||
|
||||
/* ── Idle visual: device-glyph with a soft pulse halo ────────── */
|
||||
|
||||
.pair-visual {
|
||||
position: relative;
|
||||
width: 96px;
|
||||
height: 96px;
|
||||
display: flex;
|
||||
align-items: center;
|
||||
justify-content: center;
|
||||
}
|
||||
|
||||
.pair-visual-glyph {
|
||||
width: 56px;
|
||||
height: 56px;
|
||||
color: var(--ch-signal, var(--primary-color));
|
||||
opacity: 0.85;
|
||||
}
|
||||
|
||||
.pair-pulse {
|
||||
position: absolute;
|
||||
inset: 0;
|
||||
border-radius: 50%;
|
||||
background: radial-gradient(
|
||||
circle at center,
|
||||
color-mix(in srgb, var(--ch-signal, var(--primary-color)) 28%, transparent),
|
||||
transparent 70%
|
||||
);
|
||||
animation: pairPulse 2.2s ease-in-out infinite;
|
||||
}
|
||||
|
||||
@keyframes pairPulse {
|
||||
0%, 100% { transform: scale(0.85); opacity: 0.55; }
|
||||
50% { transform: scale(1.08); opacity: 1; }
|
||||
}
|
||||
|
||||
/* ── Pairing ring + countdown ────────────────────────────────── */
|
||||
|
||||
.pair-ring-wrap {
|
||||
position: relative;
|
||||
width: 140px;
|
||||
height: 140px;
|
||||
}
|
||||
|
||||
.pair-ring {
|
||||
width: 100%;
|
||||
height: 100%;
|
||||
/* Rotate so the fill starts at 12 o'clock and progresses clockwise. */
|
||||
transform: rotate(-90deg);
|
||||
}
|
||||
|
||||
.pair-ring-bg {
|
||||
stroke: color-mix(in srgb, var(--lux-line-bold, var(--border-color)) 60%, transparent);
|
||||
}
|
||||
|
||||
.pair-ring-fg {
|
||||
stroke: var(--ch-signal, var(--primary-color));
|
||||
stroke-dasharray: 0 100;
|
||||
transition: stroke-dasharray 0.18s linear;
|
||||
filter: drop-shadow(0 0 8px color-mix(in srgb, var(--ch-signal, var(--primary-color)) 45%, transparent));
|
||||
}
|
||||
|
||||
.pair-ring-content {
|
||||
position: absolute;
|
||||
inset: 0;
|
||||
display: flex;
|
||||
flex-direction: column;
|
||||
align-items: center;
|
||||
justify-content: center;
|
||||
gap: 2px;
|
||||
pointer-events: none;
|
||||
}
|
||||
|
||||
.pair-ring-count {
|
||||
font-family: var(--font-mono, ui-monospace, SFMono-Regular, Menlo, monospace);
|
||||
font-size: 1.9rem;
|
||||
font-weight: 500;
|
||||
color: var(--lux-ink, var(--text-color));
|
||||
letter-spacing: 0.02em;
|
||||
line-height: 1;
|
||||
}
|
||||
|
||||
.pair-ring-label {
|
||||
font-size: 0.72rem;
|
||||
text-transform: uppercase;
|
||||
letter-spacing: 0.16em;
|
||||
color: var(--lux-ink-dim, var(--text-secondary));
|
||||
}
|
||||
|
||||
/* ── Status banners (not-ready / success / failed) ───────────── */
|
||||
|
||||
.pair-status {
|
||||
display: flex;
|
||||
align-items: flex-start;
|
||||
gap: 12px;
|
||||
width: 100%;
|
||||
padding: 14px 16px;
|
||||
border-radius: 8px;
|
||||
border: 1px solid var(--lux-line-bold, var(--border-color));
|
||||
background: color-mix(in srgb, var(--lux-bg-1, var(--card-bg)) 80%, transparent);
|
||||
font-size: 0.92rem;
|
||||
line-height: 1.45;
|
||||
color: var(--lux-ink, var(--text-color));
|
||||
}
|
||||
|
||||
.pair-status .icon {
|
||||
flex: 0 0 auto;
|
||||
width: 22px;
|
||||
height: 22px;
|
||||
margin-top: 1px;
|
||||
}
|
||||
|
||||
.pair-status-ok {
|
||||
border-color: color-mix(in srgb, var(--ch-signal, var(--primary-color)) 55%, transparent);
|
||||
background: color-mix(in srgb, var(--ch-signal, var(--primary-color)) 12%, transparent);
|
||||
}
|
||||
.pair-status-ok .icon { color: var(--ch-signal, var(--primary-color)); }
|
||||
|
||||
.pair-status-warn {
|
||||
border-color: color-mix(in srgb, var(--ch-amber, #d99a00) 55%, transparent);
|
||||
background: color-mix(in srgb, var(--ch-amber, #d99a00) 12%, transparent);
|
||||
}
|
||||
.pair-status-warn .icon { color: var(--ch-amber, #d99a00); }
|
||||
|
||||
.pair-status-err {
|
||||
border-color: color-mix(in srgb, var(--ch-coral, var(--danger-color)) 55%, transparent);
|
||||
background: color-mix(in srgb, var(--ch-coral, var(--danger-color)) 12%, transparent);
|
||||
}
|
||||
.pair-status-err .icon { color: var(--ch-coral, var(--danger-color)); }
|
||||
|
||||
@media (prefers-reduced-motion: reduce) {
|
||||
.pair-pulse,
|
||||
.pair-state { animation: none; }
|
||||
.pair-ring-fg { transition: none; }
|
||||
}
|
||||
|
||||
|
||||
@@ -0,0 +1,333 @@
|
||||
/**
|
||||
* Reusable pairing-flow controller — opens the `#pair-device-modal`,
|
||||
* drives its state transitions, POSTs to `/devices/pair`, and resolves
|
||||
* with the provider-returned fields so a caller can merge them into a
|
||||
* device-create payload.
|
||||
*
|
||||
* The module is driver-agnostic. Future drivers call
|
||||
* `runPairingFlow({deviceType, url})` and consume the returned `fields`
|
||||
* directly — the flow knows nothing about Nanoleaf, Tuya, Twinkly, etc.
|
||||
*
|
||||
* Backend contract:
|
||||
* POST /api/v1/devices/pair { device_type, url }
|
||||
* 200 → { fields: {...} } — success
|
||||
* 409 → device not ready / window timed out — retryable
|
||||
* 400 / 422 / 502 → terminal failure with error detail
|
||||
*/
|
||||
|
||||
import { fetchWithAuth, ApiError } from '../core/api.ts';
|
||||
import { t } from '../core/i18n.ts';
|
||||
import { Modal } from '../core/modal.ts';
|
||||
|
||||
/** Length of the visual pairing window in seconds. Most consumer IoT
|
||||
* devices open a 30s window after the user presses the pairing button;
|
||||
* the ring fills from 0 → full over this period purely as a UI hint —
|
||||
* the actual handshake duration is dictated by the backend, not this
|
||||
* timer. */
|
||||
const PAIRING_WINDOW_SECONDS = 30;
|
||||
|
||||
/** Tiny pause after a successful pair so the user sees the confirmation
|
||||
* before the modal disappears. */
|
||||
const SUCCESS_DISMISS_DELAY_MS = 450;
|
||||
|
||||
export interface PairingFlowOptions {
|
||||
/** Device type slug, matched to backend driver registry (e.g. 'nanoleaf'). */
|
||||
deviceType: string;
|
||||
/** Pairing URL — driver-specific scheme accepted (e.g. 'nanoleaf://10.0.0.5'). */
|
||||
url: string;
|
||||
/** Override the instructions i18n key. Defaults to
|
||||
* `device.${deviceType}.pair.instructions`, with fallback to
|
||||
* `pairing.instructions.default` when the type-specific key is missing. */
|
||||
instructionsKey?: string;
|
||||
}
|
||||
|
||||
export interface PairingFlowResult {
|
||||
/** Fields returned by the provider, ready to merge into the
|
||||
* device-create payload (token, client key, group id, …). */
|
||||
fields: Record<string, unknown>;
|
||||
}
|
||||
|
||||
/** Sentinel thrown when the user dismisses the modal (cancel / close /
|
||||
* backdrop / Esc). Callers should treat this as a soft cancel — not
|
||||
* an error to surface. */
|
||||
export class PairingCancelled extends Error {
|
||||
constructor() {
|
||||
super('Pairing cancelled by user');
|
||||
this.name = 'PairingCancelled';
|
||||
}
|
||||
}
|
||||
|
||||
type PairState = 'idle' | 'pairing' | 'notready' | 'success' | 'failed';
|
||||
|
||||
interface RunCtx {
|
||||
modal: PairModal;
|
||||
opts: PairingFlowOptions;
|
||||
resolve: (value: PairingFlowResult) => void;
|
||||
reject: (err: unknown) => void;
|
||||
/** AbortController for an in-flight pair request, used by Cancel. */
|
||||
abort: AbortController | null;
|
||||
/** RequestAnimationFrame/interval handle for the countdown ring. */
|
||||
countdownTimer: number | null;
|
||||
/** True once we've resolved or rejected — guards double-finalize. */
|
||||
settled: boolean;
|
||||
}
|
||||
|
||||
class PairModal extends Modal {
|
||||
constructor() { super('pair-device-modal'); }
|
||||
}
|
||||
|
||||
let _modal: PairModal | null = null;
|
||||
let _ctx: RunCtx | null = null;
|
||||
|
||||
/** Lazy single-instance modal so we don't bind listeners until first use. */
|
||||
function _getModal(): PairModal {
|
||||
if (!_modal) _modal = new PairModal();
|
||||
return _modal;
|
||||
}
|
||||
|
||||
function _byId<T extends HTMLElement = HTMLElement>(id: string): T | null {
|
||||
return document.getElementById(id) as T | null;
|
||||
}
|
||||
|
||||
/** Set the modal's `[data-pair-state]` attribute and toggle child blocks. */
|
||||
function _setState(state: PairState): void {
|
||||
const root = document.querySelector('#pair-device-modal .pair-states') as HTMLElement | null;
|
||||
if (!root) return;
|
||||
root.setAttribute('data-pair-state', state);
|
||||
const blocks = root.querySelectorAll<HTMLElement>('[data-pair-state-block]');
|
||||
blocks.forEach(b => {
|
||||
const isActive = b.getAttribute('data-pair-state-block') === state;
|
||||
b.style.display = isActive ? '' : 'none';
|
||||
});
|
||||
}
|
||||
|
||||
/** Apply the type-specific (or fallback) instruction text. */
|
||||
function _applyInstructions(opts: PairingFlowOptions): void {
|
||||
const el = _byId('pair-device-instructions');
|
||||
if (!el) return;
|
||||
const specificKey = opts.instructionsKey ?? `device.${opts.deviceType}.pair.instructions`;
|
||||
const fallbackKey = 'pairing.instructions.default';
|
||||
// If the i18n helper returns the key unchanged it means the key is missing —
|
||||
// fall back to the generic default so the user always sees real copy.
|
||||
const specific = t(specificKey);
|
||||
el.textContent = specific === specificKey ? t(fallbackKey) : specific;
|
||||
// Keep the data-i18n attribute pointing at whatever key we ended up
|
||||
// showing so `updateAllText` (triggered on language change) refreshes it.
|
||||
el.setAttribute('data-i18n', specific === specificKey ? fallbackKey : specificKey);
|
||||
}
|
||||
|
||||
/** Start the visual countdown ring. Purely cosmetic — the actual fetch
|
||||
* has its own deadline. */
|
||||
function _startCountdown(ctx: RunCtx): void {
|
||||
const ring = document.querySelector('#pair-device-modal .pair-ring-fg') as SVGCircleElement | null;
|
||||
const countEl = _byId('pair-countdown');
|
||||
if (!ring || !countEl) return;
|
||||
|
||||
const totalMs = PAIRING_WINDOW_SECONDS * 1000;
|
||||
const startedAt = performance.now();
|
||||
|
||||
// pathLength=100, so stroke-dasharray "X 100" fills X% of the circumference.
|
||||
ring.style.strokeDasharray = '0 100';
|
||||
countEl.textContent = String(PAIRING_WINDOW_SECONDS);
|
||||
|
||||
const tick = () => {
|
||||
if (ctx.settled) return;
|
||||
const elapsed = performance.now() - startedAt;
|
||||
const ratio = Math.min(1, elapsed / totalMs);
|
||||
ring.style.strokeDasharray = `${(ratio * 100).toFixed(2)} 100`;
|
||||
const remaining = Math.max(0, Math.ceil((totalMs - elapsed) / 1000));
|
||||
countEl.textContent = String(remaining);
|
||||
if (ratio < 1) {
|
||||
ctx.countdownTimer = requestAnimationFrame(tick);
|
||||
} else {
|
||||
ctx.countdownTimer = null;
|
||||
}
|
||||
};
|
||||
ctx.countdownTimer = requestAnimationFrame(tick);
|
||||
}
|
||||
|
||||
function _stopCountdown(ctx: RunCtx): void {
|
||||
if (ctx.countdownTimer !== null) {
|
||||
cancelAnimationFrame(ctx.countdownTimer);
|
||||
ctx.countdownTimer = null;
|
||||
}
|
||||
}
|
||||
|
||||
/** Fire the POST and dispatch to the appropriate post-response state. */
|
||||
async function _attemptPair(ctx: RunCtx): Promise<void> {
|
||||
if (ctx.settled) return;
|
||||
_setState('pairing');
|
||||
_startCountdown(ctx);
|
||||
|
||||
ctx.abort = new AbortController();
|
||||
try {
|
||||
const resp = await fetchWithAuth('/devices/pair', {
|
||||
method: 'POST',
|
||||
body: JSON.stringify({
|
||||
device_type: ctx.opts.deviceType,
|
||||
url: ctx.opts.url,
|
||||
}),
|
||||
signal: ctx.abort.signal,
|
||||
// The pairing window itself can be ~30s; allow a little headroom.
|
||||
timeout: 45_000,
|
||||
// Don't retry — pairing isn't idempotent and 5xx during a handshake
|
||||
// means the device side is unhappy. Surface immediately.
|
||||
retry: false,
|
||||
});
|
||||
_stopCountdown(ctx);
|
||||
ctx.abort = null;
|
||||
await _handleResponse(ctx, resp);
|
||||
} catch (err: unknown) {
|
||||
_stopCountdown(ctx);
|
||||
ctx.abort = null;
|
||||
if (ctx.settled) return;
|
||||
// AbortError surfaces when Cancel was clicked — settled was already
|
||||
// set in the cancel handler; nothing more to do.
|
||||
if ((err as { name?: string })?.name === 'AbortError') return;
|
||||
if (err instanceof ApiError && err.isAuth) {
|
||||
// The api layer already opened the login flow; just reject so
|
||||
// callers don't hang.
|
||||
_finalize(ctx, () => ctx.reject(err));
|
||||
return;
|
||||
}
|
||||
const detail = err instanceof Error ? err.message : t('api.error.network');
|
||||
_showFailure(detail);
|
||||
}
|
||||
}
|
||||
|
||||
async function _handleResponse(ctx: RunCtx, resp: Response): Promise<void> {
|
||||
if (resp.status === 200) {
|
||||
let parsed: { fields?: Record<string, unknown> } = {};
|
||||
try { parsed = await resp.json() as { fields?: Record<string, unknown> }; }
|
||||
catch { /* fall through with empty fields */ }
|
||||
const fields = parsed.fields ?? {};
|
||||
_setState('success');
|
||||
// Brief confirmation before dismissing, so the user gets feedback.
|
||||
window.setTimeout(() => {
|
||||
_finalize(ctx, () => {
|
||||
ctx.modal.forceClose();
|
||||
ctx.resolve({ fields });
|
||||
});
|
||||
}, SUCCESS_DISMISS_DELAY_MS);
|
||||
return;
|
||||
}
|
||||
|
||||
if (resp.status === 409) {
|
||||
_setState('notready');
|
||||
return;
|
||||
}
|
||||
|
||||
// 400 / 422 / 502 / any other non-2xx → terminal failure.
|
||||
let detail = '';
|
||||
try {
|
||||
const body = await resp.json() as { detail?: string };
|
||||
if (typeof body?.detail === 'string') detail = body.detail;
|
||||
} catch { /* no JSON body */ }
|
||||
_showFailure(detail || `${resp.status} ${resp.statusText}`);
|
||||
}
|
||||
|
||||
function _showFailure(detail: string): void {
|
||||
const detailEl = _byId('pair-failure-detail');
|
||||
if (detailEl) {
|
||||
// Render localized prefix + raw detail. The i18n helper supports
|
||||
// {detail} interpolation, so we use the templated form when available
|
||||
// and fall back to "Pairing failed: <detail>" assembled manually.
|
||||
const templated = t('pairing.failed', { detail });
|
||||
// If the helper returned the key unchanged it means the locale file
|
||||
// doesn't carry the key — assemble manually as a safety net.
|
||||
if (templated === 'pairing.failed' || templated.includes('{detail}')) {
|
||||
detailEl.textContent = `${t('pairing.failed_prefix')} ${detail}`.trim();
|
||||
} else {
|
||||
detailEl.textContent = templated;
|
||||
}
|
||||
}
|
||||
_setState('failed');
|
||||
}
|
||||
|
||||
function _finalize(ctx: RunCtx, work: () => void): void {
|
||||
if (ctx.settled) return;
|
||||
ctx.settled = true;
|
||||
_stopCountdown(ctx);
|
||||
if (ctx.abort) { ctx.abort.abort(); ctx.abort = null; }
|
||||
_detachHandlers();
|
||||
_ctx = null;
|
||||
work();
|
||||
}
|
||||
|
||||
// ── Event-handler refs (kept so we can detach on close) ──────────────
|
||||
|
||||
let _onStart: (() => void) | null = null;
|
||||
let _onRetry: (() => void) | null = null;
|
||||
let _onCloseTerminal: (() => void) | null = null;
|
||||
let _onCancel: (() => void) | null = null;
|
||||
let _onCloseBtn: (() => void) | null = null;
|
||||
|
||||
function _attachHandlers(ctx: RunCtx): void {
|
||||
_onStart = () => { if (!ctx.settled) void _attemptPair(ctx); };
|
||||
_onRetry = () => { if (!ctx.settled) void _attemptPair(ctx); };
|
||||
const cancelAll = () => {
|
||||
_finalize(ctx, () => {
|
||||
ctx.modal.forceClose();
|
||||
ctx.reject(new PairingCancelled());
|
||||
});
|
||||
};
|
||||
_onCancel = cancelAll;
|
||||
_onCloseTerminal = cancelAll;
|
||||
_onCloseBtn = cancelAll;
|
||||
|
||||
_byId('pair-start-btn')?.addEventListener('click', _onStart);
|
||||
_byId('pair-retry-btn')?.addEventListener('click', _onRetry);
|
||||
_byId('pair-close-btn')?.addEventListener('click', _onCloseTerminal);
|
||||
_byId('pair-cancel-btn')?.addEventListener('click', _onCancel);
|
||||
_byId('pair-device-close-btn')?.addEventListener('click', _onCloseBtn);
|
||||
}
|
||||
|
||||
function _detachHandlers(): void {
|
||||
if (_onStart) _byId('pair-start-btn')?.removeEventListener('click', _onStart);
|
||||
if (_onRetry) _byId('pair-retry-btn')?.removeEventListener('click', _onRetry);
|
||||
if (_onCloseTerminal) _byId('pair-close-btn')?.removeEventListener('click', _onCloseTerminal);
|
||||
if (_onCancel) _byId('pair-cancel-btn')?.removeEventListener('click', _onCancel);
|
||||
if (_onCloseBtn) _byId('pair-device-close-btn')?.removeEventListener('click', _onCloseBtn);
|
||||
_onStart = _onRetry = _onCloseTerminal = _onCancel = _onCloseBtn = null;
|
||||
}
|
||||
|
||||
/**
|
||||
* Open the pair modal, run the pairing handshake on user gesture, and
|
||||
* resolve with the provider-returned `fields`. Rejects with
|
||||
* {@link PairingCancelled} on user dismiss, or with the underlying error
|
||||
* for terminal failures.
|
||||
*
|
||||
* Only one pairing flow can be active at a time — calling this while
|
||||
* another is in flight rejects the previous one as cancelled.
|
||||
*/
|
||||
export function runPairingFlow(opts: PairingFlowOptions): Promise<PairingFlowResult> {
|
||||
// If another flow is mid-run, soft-cancel it. The caller of the
|
||||
// previous run will see a PairingCancelled rejection, matching what
|
||||
// happens when the user clicks Cancel.
|
||||
if (_ctx && !_ctx.settled) {
|
||||
const prev = _ctx;
|
||||
_finalize(prev, () => {
|
||||
prev.modal.forceClose();
|
||||
prev.reject(new PairingCancelled());
|
||||
});
|
||||
}
|
||||
|
||||
return new Promise<PairingFlowResult>((resolve, reject) => {
|
||||
const modal = _getModal();
|
||||
_applyInstructions(opts);
|
||||
_setState('idle');
|
||||
|
||||
const ctx: RunCtx = {
|
||||
modal,
|
||||
opts,
|
||||
resolve,
|
||||
reject,
|
||||
abort: null,
|
||||
countdownTimer: null,
|
||||
settled: false,
|
||||
};
|
||||
_ctx = ctx;
|
||||
_attachHandlers(ctx);
|
||||
modal.open();
|
||||
});
|
||||
}
|
||||
@@ -2939,5 +2939,16 @@
|
||||
"streams.group.audio_processing": "Audio Processing",
|
||||
"section.empty.audio_processing_templates": "No audio processing templates yet. Click + to create one.",
|
||||
"audio_source.group.capture": "Capture Sources",
|
||||
"audio_source.group.processed": "Processed Sources"
|
||||
"audio_source.group.processed": "Processed Sources",
|
||||
"pairing.title": "Pair Device",
|
||||
"pairing.instructions.default": "Press and hold the pairing button on your device, then click Start. Devices typically open a 30-second pairing window — be ready to act quickly.",
|
||||
"pairing.start": "Start pairing",
|
||||
"pairing.pairing": "Pairing…",
|
||||
"pairing.cancel": "Cancel",
|
||||
"pairing.retry": "Try again",
|
||||
"pairing.close": "Close",
|
||||
"pairing.success": "Paired successfully",
|
||||
"pairing.not_ready": "Device didn't respond. Press the pairing button on your device, then try again.",
|
||||
"pairing.failed": "Pairing failed: {detail}",
|
||||
"pairing.failed_prefix": "Pairing failed:"
|
||||
}
|
||||
|
||||
@@ -2619,5 +2619,16 @@
|
||||
"streams.group.audio_processing": "Обработка звука",
|
||||
"section.empty.audio_processing_templates": "Пока нет шаблонов обработки звука. Нажмите +, чтобы создать.",
|
||||
"audio_source.group.capture": "Захват звука",
|
||||
"audio_source.group.processed": "Обработанные источники"
|
||||
"audio_source.group.processed": "Обработанные источники",
|
||||
"pairing.title": "Сопряжение устройства",
|
||||
"pairing.instructions.default": "Нажмите и удерживайте кнопку сопряжения на устройстве, затем нажмите «Начать». Устройства обычно открывают окно сопряжения на 30 секунд — действуйте быстро.",
|
||||
"pairing.start": "Начать сопряжение",
|
||||
"pairing.pairing": "Сопряжение…",
|
||||
"pairing.cancel": "Отмена",
|
||||
"pairing.retry": "Повторить",
|
||||
"pairing.close": "Закрыть",
|
||||
"pairing.success": "Успешно сопряжено",
|
||||
"pairing.not_ready": "Устройство не ответило. Нажмите кнопку сопряжения на устройстве и попробуйте снова.",
|
||||
"pairing.failed": "Сопряжение не удалось: {detail}",
|
||||
"pairing.failed_prefix": "Сопряжение не удалось:"
|
||||
}
|
||||
|
||||
@@ -2614,5 +2614,16 @@
|
||||
"streams.group.audio_processing": "音频处理",
|
||||
"section.empty.audio_processing_templates": "暂无音频处理模板。点击 + 创建一个。",
|
||||
"audio_source.group.capture": "音频捕获",
|
||||
"audio_source.group.processed": "已处理的源"
|
||||
"audio_source.group.processed": "已处理的源",
|
||||
"pairing.title": "配对设备",
|
||||
"pairing.instructions.default": "请按住设备上的配对按钮，然后点击「开始」。设备通常会打开 30 秒的配对窗口——请准备好快速操作。",
|
||||
"pairing.start": "开始配对",
|
||||
"pairing.pairing": "配对中…",
|
||||
"pairing.cancel": "取消",
|
||||
"pairing.retry": "重试",
|
||||
"pairing.close": "关闭",
|
||||
"pairing.success": "配对成功",
|
||||
"pairing.not_ready": "设备未响应。请按下设备上的配对按钮后重试。",
|
||||
"pairing.failed": "配对失败：{detail}",
|
||||
"pairing.failed_prefix": "配对失败："
|
||||
}
|
||||
|
||||
@@ -236,6 +236,7 @@
|
||||
{% include 'modals/setup-required.html' %}
|
||||
{% include 'modals/confirm.html' %}
|
||||
{% include 'modals/add-device.html' %}
|
||||
{% include 'modals/pair-device.html' %}
|
||||
{% include 'modals/capture-template.html' %}
|
||||
{% include 'modals/test-template.html' %}
|
||||
{% include 'modals/test-stream.html' %}
|
||||
|
||||
@@ -0,0 +1,86 @@
|
||||
<!-- Pair Device Modal — reusable handshake UI for drivers that require a
|
||||
physical pairing action on the device (Nanoleaf, Tuya, Twinkly, …).
|
||||
|
||||
The runtime controller (`features/pairing-flow.ts`) populates the
|
||||
instructions text, drives state transitions (idle → pairing → success
|
||||
| not_ready | failed), and resolves a Promise with the provider-returned
|
||||
fields. State blocks are toggled via the `[data-pair-state]` attribute
|
||||
on `.pair-states`; only the active block is visible. -->
|
||||
<div id="pair-device-modal" class="modal" role="dialog" aria-modal="true" aria-labelledby="pair-device-modal-title">
|
||||
<div class="modal-content" style="max-width: 480px;">
|
||||
<div class="modal-header">
|
||||
<h2 id="pair-device-modal-title">
|
||||
<svg class="icon" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M9 12h6"/><path d="M12 9v6"/><circle cx="12" cy="12" r="9"/></svg>
|
||||
<span data-i18n="pairing.title">Pair Device</span>
|
||||
</h2>
|
||||
<button class="modal-close-btn" id="pair-device-close-btn" title="Close" data-i18n-aria-label="aria.close">✕</button>
|
||||
</div>
|
||||
<div class="modal-body">
|
||||
<p id="pair-device-instructions" class="pair-instructions" data-i18n="pairing.instructions.default">
|
||||
Press and hold the pairing button on your device, then click Start. Devices typically open a 30-second pairing window — be ready to act quickly.
|
||||
</p>
|
||||
|
||||
<div class="pair-states" data-pair-state="idle">
|
||||
|
||||
<!-- ── IDLE ────────────────────────────────────────── -->
|
||||
<div class="pair-state pair-state-idle" data-pair-state-block="idle">
|
||||
<div class="pair-visual pair-visual-idle" aria-hidden="true">
|
||||
<span class="pair-pulse"></span>
|
||||
<svg class="icon pair-visual-glyph" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.6" stroke-linecap="round" stroke-linejoin="round"><circle cx="12" cy="12" r="3"/><path d="M19.07 4.93a10 10 0 0 1 0 14.14M4.93 4.93a10 10 0 0 0 0 14.14M16.24 7.76a6 6 0 0 1 0 8.48M7.76 7.76a6 6 0 0 0 0 8.48"/></svg>
|
||||
</div>
|
||||
<button type="button" class="btn btn-primary pair-action" id="pair-start-btn" data-i18n="pairing.start">
|
||||
Start pairing
|
||||
</button>
|
||||
</div>
|
||||
|
||||
<!-- ── PAIRING (progress ring + countdown) ─────────── -->
|
||||
<div class="pair-state pair-state-pairing" data-pair-state-block="pairing" style="display: none;">
|
||||
<div class="pair-ring-wrap" role="status" aria-live="polite">
|
||||
<svg class="pair-ring" viewBox="0 0 100 100" aria-hidden="true">
|
||||
<circle class="pair-ring-bg" cx="50" cy="50" r="44" fill="none" stroke-width="4"/>
|
||||
<circle class="pair-ring-fg" cx="50" cy="50" r="44" fill="none" stroke-width="4" stroke-linecap="round" pathLength="100"/>
|
||||
</svg>
|
||||
<div class="pair-ring-content">
|
||||
<div class="pair-ring-count" id="pair-countdown">30</div>
|
||||
<div class="pair-ring-label" data-i18n="pairing.pairing">Pairing…</div>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<!-- ── NOT READY (409 retryable) ───────────────────── -->
|
||||
<div class="pair-state pair-state-notready" data-pair-state-block="notready" style="display: none;">
|
||||
<div class="pair-status pair-status-warn">
|
||||
<svg class="icon" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="m21.73 18-8-14a2 2 0 0 0-3.48 0l-8 14A2 2 0 0 0 4 21h16a2 2 0 0 0 1.73-3"/><path d="M12 9v4"/><path d="M12 17h.01"/></svg>
|
||||
<span data-i18n="pairing.not_ready">Device didn't respond. Press the pairing button on your device, then try again.</span>
|
||||
</div>
|
||||
<button type="button" class="btn btn-primary pair-action" id="pair-retry-btn" data-i18n="pairing.retry">
|
||||
Try again
|
||||
</button>
|
||||
</div>
|
||||
|
||||
<!-- ── SUCCESS (brief confirmation) ────────────────── -->
|
||||
<div class="pair-state pair-state-success" data-pair-state-block="success" style="display: none;">
|
||||
<div class="pair-status pair-status-ok">
|
||||
<svg class="icon" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M20 6 9 17l-5-5"/></svg>
|
||||
<span data-i18n="pairing.success">Paired successfully</span>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<!-- ── FAILED (terminal) ───────────────────────────── -->
|
||||
<div class="pair-state pair-state-failed" data-pair-state-block="failed" style="display: none;">
|
||||
<div class="pair-status pair-status-err">
|
||||
<svg class="icon" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><circle cx="12" cy="12" r="10"/><path d="m15 9-6 6"/><path d="m9 9 6 6"/></svg>
|
||||
<span id="pair-failure-detail" data-i18n="pairing.failed">Pairing failed.</span>
|
||||
</div>
|
||||
<button type="button" class="btn btn-secondary pair-action" id="pair-close-btn" data-i18n="pairing.close">
|
||||
Close
|
||||
</button>
|
||||
</div>
|
||||
|
||||
</div>
|
||||
</div>
|
||||
<div class="modal-footer">
|
||||
<button type="button" class="btn btn-icon btn-secondary" id="pair-cancel-btn" title="Cancel" data-i18n-aria-label="aria.cancel">✕</button>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
@@ -203,3 +203,140 @@ class TestBatchStates:
|
||||
resp = client.get("/api/v1/devices/batch/states")
|
||||
assert resp.status_code == 200
|
||||
assert "states" in resp.json()
|
||||
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# PAIRING
|
||||
# ---------------------------------------------------------------------------
|
||||
|
||||
|
||||
class _PairableProviderStub:
|
||||
"""Test double that exercises the four pair_device outcomes.
|
||||
|
||||
Registered into the provider registry at test-time and unregistered
|
||||
afterwards so the global registry stays clean across tests.
|
||||
"""
|
||||
|
||||
def __init__(self, outcome: str):
|
||||
self._outcome = outcome
|
||||
|
||||
@property
|
||||
def device_type(self) -> str:
|
||||
return "_pair_test"
|
||||
|
||||
@property
|
||||
def capabilities(self) -> set:
|
||||
return {"requires_pairing"}
|
||||
|
||||
def create_client(self, config, *, deps): # pragma: no cover -- not used here
|
||||
raise AssertionError("Stub provider should not be asked to create a client")
|
||||
|
||||
async def check_health(self, url, http_client, prev_health=None): # pragma: no cover
|
||||
raise AssertionError("Stub provider should not be asked for health")
|
||||
|
||||
async def validate_device(self, url): # pragma: no cover
|
||||
return {}
|
||||
|
||||
async def pair_device(self, url: str):
|
||||
from ledgrab.core.devices.led_client import PairingNotReady
|
||||
|
||||
if self._outcome == "success":
|
||||
return {"_pair_test_token": "token-abc", "_pair_test_meta": 42}
|
||||
if self._outcome == "not_ready":
|
||||
raise PairingNotReady("Press the device button and try again.")
|
||||
if self._outcome == "invalid_url":
|
||||
raise ValueError("URL is missing a host")
|
||||
if self._outcome == "boom":
|
||||
raise RuntimeError("transport blew up")
|
||||
if self._outcome == "malformed":
|
||||
return "not-a-dict" # type: ignore[return-value]
|
||||
if self._outcome == "not_implemented":
|
||||
raise NotImplementedError("paired? what is paired?")
|
||||
raise AssertionError(f"unknown outcome: {self._outcome}")
|
||||
|
||||
|
||||
@pytest.fixture
|
||||
def pair_stub_registered():
|
||||
"""Register a test provider for the duration of one test."""
|
||||
from ledgrab.core.devices import led_client as _led_client
|
||||
|
||||
registered: dict = {}
|
||||
|
||||
def _register(outcome: str):
|
||||
provider = _PairableProviderStub(outcome)
|
||||
_led_client.register_provider(provider) # type: ignore[arg-type]
|
||||
registered["type"] = provider.device_type
|
||||
return provider
|
||||
|
||||
yield _register
|
||||
|
||||
if "type" in registered:
|
||||
_led_client._provider_registry.pop(registered["type"], None)
|
||||
|
||||
|
||||
class TestPairDevice:
|
||||
def test_returns_provider_fields_on_success(self, client, pair_stub_registered):
|
||||
pair_stub_registered("success")
|
||||
resp = client.post(
|
||||
"/api/v1/devices/pair",
|
||||
json={"device_type": "_pair_test", "url": "test://host"},
|
||||
)
|
||||
assert resp.status_code == 200, resp.text
|
||||
assert resp.json() == {"fields": {"_pair_test_token": "token-abc", "_pair_test_meta": 42}}
|
||||
|
||||
def test_unknown_device_type_returns_400(self, client):
|
||||
resp = client.post(
|
||||
"/api/v1/devices/pair",
|
||||
json={"device_type": "nonexistent_zzz", "url": "x://y"},
|
||||
)
|
||||
assert resp.status_code == 400
|
||||
assert "unknown device type" in resp.json()["detail"].lower()
|
||||
|
||||
def test_not_implemented_returns_400(self, client, pair_stub_registered):
|
||||
pair_stub_registered("not_implemented")
|
||||
resp = client.post(
|
||||
"/api/v1/devices/pair",
|
||||
json={"device_type": "_pair_test", "url": "test://host"},
|
||||
)
|
||||
assert resp.status_code == 400
|
||||
assert "does not support pairing" in resp.json()["detail"]
|
||||
|
||||
def test_pairing_not_ready_returns_409(self, client, pair_stub_registered):
|
||||
pair_stub_registered("not_ready")
|
||||
resp = client.post(
|
||||
"/api/v1/devices/pair",
|
||||
json={"device_type": "_pair_test", "url": "test://host"},
|
||||
)
|
||||
assert resp.status_code == 409
|
||||
assert "press" in resp.json()["detail"].lower()
|
||||
|
||||
def test_invalid_url_returns_422(self, client, pair_stub_registered):
|
||||
pair_stub_registered("invalid_url")
|
||||
resp = client.post(
|
||||
"/api/v1/devices/pair",
|
||||
json={"device_type": "_pair_test", "url": "test://host"},
|
||||
)
|
||||
assert resp.status_code == 422
|
||||
assert "host" in resp.json()["detail"]
|
||||
|
||||
def test_transport_exception_returns_502(self, client, pair_stub_registered):
|
||||
pair_stub_registered("boom")
|
||||
resp = client.post(
|
||||
"/api/v1/devices/pair",
|
||||
json={"device_type": "_pair_test", "url": "test://host"},
|
||||
)
|
||||
assert resp.status_code == 502
|
||||
assert "pairing failed" in resp.json()["detail"].lower()
|
||||
|
||||
def test_malformed_provider_result_returns_500(self, client, pair_stub_registered):
|
||||
pair_stub_registered("malformed")
|
||||
resp = client.post(
|
||||
"/api/v1/devices/pair",
|
||||
json={"device_type": "_pair_test", "url": "test://host"},
|
||||
)
|
||||
assert resp.status_code == 500
|
||||
assert "malformed" in resp.json()["detail"].lower()
|
||||
|
||||
def test_missing_required_fields_returns_422(self, client):
|
||||
resp = client.post("/api/v1/devices/pair", json={"device_type": "nanoleaf"})
|
||||
assert resp.status_code == 422
|
||||
|
||||
Reference in New Issue
Block a user