filmopen_relay

A snapshot

This specification is a copy of docs/software/packages/filmopen_relay.md in the application’s repository, taken at commit 0b4fe88 of 11 November 2026. It is imported byte for byte and is not edited here; a change is made there, and arrives with the next snapshot.

Generated by scripts/package_digest.py; regenerate, never edit.

Remote control (Software Specification §6.6c): the one socket this device holds to filmopen.ai’s relay, wss://<kFilmOpenDomain>/v1/relay/socket, so that the person’s chat app reaches this device’s commands through the website, and a device that lends a plug-in hears the lending notices at once.

Flutter. 7 files, 890 lines under lib/; 3 tests in 3 files. Barrel: lib/filmopen_relay.dart.

Depends on

• filmopen_format — uses nothing by name the digest could see
• filmopen_l10n — uses nothing by name the digest could see
• filmopen_state — uses CommandCaller, CommandRegistry, CommandResult, DeviceRegistration, Lending, Settings, kFilmOpenDomain, runningPlatformName
• filmopen_store — uses AppLog
• filmopen_ui — uses SectionCard, showMessage

Used by

filmopen_app

Public API

What the barrel exports, file by file. A name is class, enum, mixin, extension, typedef, a top-level function, getter, setter or variable; under a class, its public constructors, fields, getters, setters and methods.

lib/src/relay_client.dart

• enum RelayPhase — Where the socket stands, as the card shows it.
  • values: off, connecting, connected, stopped
• class RelayStatus — The socket’s phase, and for a stopped one, why: superseded, a close code (4002) or a refused upgrade’s status (401).
  • const RelayStatus(this.phase, [this.code])
  • final RelayPhase phase — The phase.
  • final String? code — Why it stopped; null in every other phase.
• typedef typedef MintedMedia — A picture the app minted a link for, as resources/read answers it: its type, its bytes and the link’s life left.
• typedef typedef MintedLink — A link the app minted, as resources/list names it: the link, a name that names no entity, and its type.
• class RelayLifetime — One connection attempt and the socket it got (§6.6c): made when the socket becomes eligible or the 10-second retry fires, ended when eligibility ends, the socket drops or stops.
  • final int index — From 1, in the process: the only identity the log carries.
  • final String account — The account it was made for: another account’s sign-in ends it.
  • bool get live — Whether it has not ended.
• class RelayClient — The relay client: eligibility, the lifetime, connecting, the frames and the closes (§6.6c).
  • RelayClient({ required this.accessToken, required this.account, required this.device, required this.version, required this.platform, this.displayNa…

lib/src/relay_socket_stub.dart

• variable const bool canHoldRelaySocket — Whether this platform can hold a socket to the relay: not the web build, which has no remote control.
• function Future<RelaySocket> connectRelaySocket(Uri url, Map<String, String> headers) — Answers that no socket is available here.

lib/src/relay_socket_types.dart

• class RelaySocket — What the relay client needs of a socket, so a test can stand in for one.
  • Stream<Object?> get frames — The frames received: a String for a text frame, bytes for a binary one.
  • void send(String text) — Sends [text] as one text frame.
  • void close(int code) — Closes the socket with [code].
  • int? get closeCode — The close code once closed, or null (none received, or a dropped connection).
• typedef typedef RelayConnector — Opens a socket to [url] with [headers] on the upgrade request.
• class RelayUpgradeRefused — The upgrade was answered with [status] instead of 101 (§6.6c), and dart:io’s [message]; its body is not exposed.
  • const RelayUpgradeRefused(this.status, {this.message})
  • final int status — The HTTP status of the refusal.
  • final String? message — What the socket’s refusal said, where it said something.

lib/src/remote_control_card.dart

• class RemoteControlCard — Remote control in Settings (§6.6c, §9): the switch, the device’s name, the state, and while connected the connector address a chat app adds.
  • const RemoteControlCard({super.key, required this.client, required this.username, required this.claimDeviceName})
  • final RelayClient client — The client the switch turns and whose state is shown.
  • final String? username — The account’s primary username, which the connector address names; null before the names are read.
  • final Future<bool> Function(BuildContext context) claimDeviceName — The root’s door to the device-name dialog: answers whether the device has a name now (§6.6b).

Internal

Files under lib/ the barrel does not reach; nothing outside the package may import them.

• lib/src/relay_socket_io.dart: canHoldRelaySocket, connectRelaySocket, _IoRelaySocket