Module gotify 

The Gotify connector: WebSocket receive stream, /application + /message REST lookups, the subscription matcher, and the reconnecting subsystem pump that routes matched messages into the host’s sessions.

Everything the connector needs from the workspace arrives through the GotifyHost port, so this module stays stream + mapping and is testable offline.

Re-exports

use std::collections::HashMap; 🔒

use std::time::Duration; 🔒

use std::time::Instant; 🔒

use anyhow::Context; 🔒

use forge_primitives::GotifyConfig; 🔒

use forge_primitives::GotifyMessage; 🔒

use forge_primitives::GotifySubscription; 🔒

use futures::SinkExt; 🔒

use futures::StreamExt; 🔒

use serde::Deserialize; 🔒

use serde::Deserialize; 🔒

use tokio::net::TcpStream; 🔒

use tokio::sync::mpsc; 🔒

use tokio::sync::oneshot; 🔒

use tokio_tungstenite::tungstenite::Bytes; 🔒

use tokio_tungstenite::tungstenite::Message; 🔒

use tokio_tungstenite::MaybeTlsStream; 🔒

use tokio_tungstenite::WebSocketStream; 🔒

use tokio_tungstenite::connect_async; 🔒

Structs

GotifyApp 🔒

One entry of Gotify’s GET /application response. Fields beyond id + name (token, description, image) are ignored.

GotifyMessages 🔒

Gotify’s GET /message paged response. Only the newest page of messages is consumed; the paging cursor is ignored - a catch-up read wants the newest N, not the full history.

GotifyRecent

One catch-up notification from GET /message, resolved for a gotify__recent reply: the application display name (from the appid, or the id as a string when the app index hasn’t seen it), title, message body, priority, and the server’s verbatim RFC3339 timestamp.

GotifyStream 🔒

An open Gotify receive stream.

Enums

GotifyEvent 🔒

Connection-lifecycle + message events from the stream task to the subsystem pump.

PumpOutcome 🔒

How a pumped stream ended, steering the reconnect loop.

Constants

BACKOFF_CAP 🔒

BACKOFF_START 🔒

Reconnect backoff: starts at 500ms, doubles per failed/short-lived connect, caps at 30s, and resets to the floor only after a connection proves healthy (see MIN_HEALTHY_UPTIME).

CONNECT_TIMEOUT 🔒

Dial timeout so a stuck connect_async (no OS-level deadline) can’t hang the loop; the dial is also raced against shutdown so a signal is observed promptly rather than bounded by the OS TCP timeout.

IDLE_DEADLINE 🔒

Treat an established stream’s path as dead when no frame (message, server ping, or pong) arrives within this window. Sits comfortably past both 2x PING_INTERVAL and Gotify’s own ~45s server-ping period, so a healthy but quiet stream never trips it; a half-open socket left by a silent network drop does, which breaks the read loop into a reconnect.

MIN_HEALTHY_UPTIME 🔒

Minimum time a connection must stay up to count as healthy. A session that drops sooner keeps the backoff escalating, so an accept-then-drop server (post-upgrade auth reject, an idle-conn-dropping proxy) can’t spin at the 500ms floor.

PING_INTERVAL 🔒

Send a WebSocket keepalive ping this often on an established stream, so a half-open path surfaces as an unanswered ping (write error or no returning pong) instead of a silently blocked read that never wakes.

RECENT_FETCH_WINDOW 🔒

Newest /message window pulled before client-side app + priority filtering. Gotify’s /message filters by neither, so we fetch the newest page and narrow locally; 200 is its per-request maximum.

REST_TIMEOUT 🔒

Per-request timeout for the read-only REST lookups (/application, /message) - keep a slow or unreachable server from stalling subsystem start or a tool call.

Traits

GotifyHost

The host port, implemented by forge-workspace. The only workspace-side state, delivery or TLS-trust plumbing a connector may reach, so this crate stays stream + mapping.

Functions

app_index

Fetch the server’s application list and fold it into a name->appid map. Inbound stream messages carry the numeric appid, so the map resolves an application name filter to the id to match against.

app_names

The server’s application NAMEs (from GET /application), in the order the server returns them. Backs gotify__apps so a session can self-discover which apps it may subscribe to.

build_app_index 🔒

build_app_names 🔒

build_id_index 🔒

fetch_apps 🔒

GET the server’s application list. Shared by the name->id index, the gotify__apps name list, and gotify__recent’s appid->name resolution.

fetch_messages 🔒

filter_recent 🔒

Resolve appid->name, filter by app + priority, sort newest-first (by monotonic id), and truncate to limit. App matching mirrors route: an unresolved appid never matches a non-empty name filter (its numeric display string can’t sneak past), though its display app still falls back to that id string.

idle_past_deadline 🔒

Whether the stream has gone silent past IDLE_DEADLINE as of now - no inbound frame refreshed last_activity in time, so the path is treated as dead. Any frame resets last_activity, which resets this.

matching_subscriptions

The subscriptions whose min_priority and applications filters priority and resolved_app satisfy, in set order. resolved_app is the message’s application NAME resolved from the app index; an unresolved appid matches only an empty (match-any) filter set, never a filter that happens to list the id numerically.

next_backoff 🔒

Next reconnect delay after a session ended: reset to the floor when the connection proved healthy (stayed up past MIN_HEALTHY_UPTIME), else escalate (double, capped at BACKOFF_CAP).

normalize 🔒

Parse a raw stream Text frame into a typed GotifyMessage.

recent_messages

The most recent notifications, newest first, filtered by application NAME (empty = any) and min_priority (None = any), capped at limit. Fetches the newest /message window plus /application (for appid-> name), then narrows locally - Gotify’s /message filters by neither.

refresh_app_index

Fetch the Gotify /application list and store the name->appid map. Warns (never silently drops) on failure - an unresolved index would otherwise leave every application-name-filtered subscription silently matching nothing while the stream still reports connected. Returns whether the index was stored, so a caller that owes the user an answer about the names can give one.

rest_client 🔒

A reqwest client for the read-only REST lookups, carrying the shared native-roots trust extension every forge HTTPS site uses.

route 🔒

Match msg against every active subscription and deliver one message per match. Multiple matches fan out to every subscriber.

run 🔒

Long-lived reconnect loop: connect (emit GotifyEvent::Connected), forward each message as GotifyEvent::Message, and on drop/error emit GotifyEvent::Disconnected then retry with exponential backoff. The backoff resets to the floor only after a healthy session (one that stayed up past MIN_HEALTHY_UPTIME); a fast drop or failed dial keeps it escalating. Exits when shutdown fires or the sender is dropped.

run_subsystem

The Gotify subsystem pump: run the reconnecting stream task and translate its events into host state + message routing. Holds the host for its lifetime - the host impl is the weak boundary, so a workspace-backed host degrades to no-ops once the workspace drops; exits when shutdown fires or the stream task ends, dropping its own handle to the stream task so that exits too.

stream_url 🔒