Skip to main content

scribe_client/
channel.rs

1//! The real-time document channel (`documents:<id>` over `/socket`).
2
3use std::{collections::VecDeque, time::Duration};
4
5use futures_util::{SinkExt, StreamExt};
6use serde::{Deserialize, Serialize};
7use serde_json::Value;
8use tokio::{net::TcpStream, time::Instant};
9use tokio_tungstenite::{
10    tungstenite::{error::ProtocolError, Error as WsError, Message},
11    MaybeTlsStream, WebSocketStream,
12};
13
14use crate::{
15    error::ScribeError,
16    model::{OutputFormat, Stage},
17};
18
19type WsStream = WebSocketStream<MaybeTlsStream<TcpStream>>;
20
21/// A Phoenix channel wire-protocol frame: `[join_ref, ref, topic, event, payload]`.
22type RawFrame = (Option<String>, Option<String>, String, String, Value);
23
24/// How often to send a heartbeat while waiting for a frame. The server closes
25/// a connection it has heard nothing from for about 66 seconds, however much
26/// it's sending; 30 seconds is what Phoenix's own client uses.
27const HEARTBEAT_INTERVAL: Duration = Duration::from_secs(30);
28
29/// An event pushed asynchronously over a [`DocumentChannel`], outside of a
30/// direct reply to something we sent.
31#[derive(Debug, Clone, PartialEq, Serialize)]
32#[serde(tag = "type", rename_all = "snake_case")]
33pub enum ChannelEvent {
34    /// A conversion's stage or progress changed.
35    Status {
36        format: OutputFormat,
37        stage: Stage,
38        progress: f64,
39    },
40    /// A chunk of streamed HTML content. Only sent for the `html_stream`
41    /// format while it's still converting.
42    Chunk { content: String },
43    /// A format finished converting.
44    ConversionComplete {
45        format: OutputFormat,
46        output_id: String,
47    },
48    /// The server reported an error unrelated to a specific request we
49    /// made (e.g. a conversion failed after it had already started).
50    Error { reason: String },
51    /// The document is password-protected and hasn't been unlocked yet.
52    /// Pushed on join, since a locked document has no outputs and would
53    /// otherwise look like a silent channel. Prompt for the password and
54    /// pass it to [`DocumentChannel::start_conversion`].
55    PasswordRequired,
56}
57
58#[derive(Debug, Deserialize)]
59struct ReplyPayload {
60    status: String,
61    #[serde(default)]
62    response: Value,
63}
64
65#[derive(Debug, Deserialize)]
66struct ErrorReason {
67    reason: String,
68    #[serde(default)]
69    purchase_url: Option<String>,
70}
71
72/// A live connection to a document's real-time channel, joined via
73/// [`crate::ScribeClient::open_document_channel`].
74///
75/// Progress on formats that were already converting (or complete) when the
76/// channel was joined arrives as [`ChannelEvent`]s from [`Self::next_event`]
77/// just like anything started with [`Self::start_conversion`] after joining.
78///
79/// Heartbeats keep the connection open only while a call on this channel is
80/// waiting, so keep calling [`Self::next_event`] during a conversion. The
81/// connection can still be lost, for example to a network failure or a server
82/// restart. A conversion carries on without it: open a new channel on the same
83/// document, and don't upload it again.
84pub struct DocumentChannel {
85    ws: WsStream,
86    topic: String,
87    join_ref: String,
88    next_ref: u64,
89    pending: VecDeque<ChannelEvent>,
90    next_heartbeat: Instant,
91}
92
93impl DocumentChannel {
94    pub(crate) async fn join(mut ws: WsStream, document_id: &str) -> Result<Self, ScribeError> {
95        let topic = format!("documents:{document_id}");
96        let join_ref = "1".to_string();
97        send_frame(
98            &mut ws,
99            Some(&join_ref),
100            &join_ref,
101            &topic,
102            "phx_join",
103            Value::Object(serde_json::Map::new()),
104        )
105        .await?;
106        let mut channel = DocumentChannel {
107            ws,
108            topic,
109            join_ref: join_ref.clone(),
110            next_ref: 2,
111            pending: VecDeque::new(),
112            next_heartbeat: Instant::now() + HEARTBEAT_INTERVAL,
113        };
114        channel.await_reply(&join_ref).await?;
115        Ok(channel)
116    }
117
118    /// Starts converting the joined document to `format`, using its current
119    /// settings. If that format is already complete, the server returns its
120    /// existing output id instead of starting a new conversion. Returns
121    /// immediately with the output id; progress arrives via subsequent
122    /// [`Self::next_event`] calls.
123    ///
124    /// # Errors
125    ///
126    /// Returns [`ScribeError::NotFound`]/[`ScribeError::Forbidden`] if the
127    /// document doesn't exist or isn't owned by the caller,
128    /// [`ScribeError::ConversionInProgress`] if any non-preview conversion
129    /// of the document is running, including that format and the
130    /// `html_stream` that creating the document started (wait for its
131    /// [`ChannelEvent::ConversionComplete`], then call this again),
132    /// [`ScribeError::RateLimited`] if too many conversions were started too
133    /// quickly,
134    /// [`ScribeError::NeedsPurchase`] if the account is out of page
135    /// credits, or [`ScribeError::PasswordRequired`] if the document is a
136    /// protected file and `password` was `None` or wrong.
137    ///
138    /// `password` unlocks a password-protected document. It's stored
139    /// against the document, so later conversions of other formats don't
140    /// need it again. A wrong password isn't detected here — the server
141    /// accepts it, the converter rejects it, and an
142    /// [`ChannelEvent::Error`] with reason `invalid_password` arrives from
143    /// [`Self::next_event`]; retry this call with a corrected password.
144    pub async fn start_conversion(
145        &mut self,
146        format: OutputFormat,
147        password: Option<&str>,
148    ) -> Result<String, ScribeError> {
149        let ref_ = self.take_ref();
150        let mut payload = serde_json::json!({ "format": format.as_str() });
151        if let Some(password) = password {
152            payload["password"] = Value::String(password.to_string());
153        }
154        send_frame(
155            &mut self.ws,
156            Some(&self.join_ref),
157            &ref_,
158            &self.topic,
159            "start_conversion",
160            payload,
161        )
162        .await?;
163        let response = self.await_reply(&ref_).await?;
164        response
165            .get("output_id")
166            .and_then(Value::as_str)
167            .map(str::to_string)
168            .ok_or(ScribeError::ChannelClosed)
169    }
170
171    /// # Errors
172    ///
173    /// Returns [`ScribeError::WebSocket`] if the connection fails, or
174    /// [`ScribeError::ChannelClosed`] if it closes before another event
175    /// arrives.
176    pub async fn next_event(&mut self) -> Result<ChannelEvent, ScribeError> {
177        if let Some(event) = self.pending.pop_front() {
178            return Ok(event);
179        }
180        loop {
181            let (_, _, topic, event, payload) = self.recv_frame().await?;
182            if topic != self.topic {
183                continue;
184            }
185            if let Some(event) = parse_event(&event, &payload) {
186                return Ok(event);
187            }
188        }
189    }
190
191    /// Closes the connection. One that's already closed or lost is fine, since
192    /// that's what this is for.
193    ///
194    /// # Errors
195    ///
196    /// Returns [`ScribeError::WebSocket`] if closing the connection fails with
197    /// it still open.
198    pub async fn close(mut self) -> Result<(), ScribeError> {
199        match self.ws.close(None).await {
200            Ok(())
201            | Err(
202                WsError::ConnectionClosed
203                | WsError::AlreadyClosed
204                | WsError::Protocol(ProtocolError::SendAfterClosing)
205                | WsError::Io(_),
206            ) => Ok(()),
207            Err(e) => Err(ScribeError::WebSocket(Box::new(e))),
208        }
209    }
210
211    fn take_ref(&mut self) -> String {
212        let r = self.next_ref.to_string();
213        self.next_ref += 1;
214        r
215    }
216
217    async fn send_heartbeat(&mut self) -> Result<(), ScribeError> {
218        let ref_ = self.take_ref();
219        self.next_heartbeat = Instant::now() + HEARTBEAT_INTERVAL;
220        send_frame(
221            &mut self.ws,
222            None,
223            &ref_,
224            "phoenix",
225            "heartbeat",
226            Value::Object(serde_json::Map::new()),
227        )
228        .await
229    }
230
231    async fn recv_frame(&mut self) -> Result<RawFrame, ScribeError> {
232        loop {
233            if Instant::now() >= self.next_heartbeat {
234                self.send_heartbeat().await?;
235            }
236            let Ok(message) = tokio::time::timeout_at(self.next_heartbeat, self.ws.next()).await
237            else {
238                continue;
239            };
240            return match message {
241                Some(Ok(Message::Text(text))) => {
242                    Ok(serde_json::from_str::<RawFrame>(text.as_str())?)
243                }
244                Some(Ok(
245                    Message::Ping(_) | Message::Pong(_) | Message::Frame(_) | Message::Binary(_),
246                )) => continue,
247                Some(Ok(Message::Close(_))) | None => Err(ScribeError::ChannelClosed),
248                Some(Err(e)) => Err(ScribeError::WebSocket(Box::new(e))),
249            };
250        }
251    }
252
253    /// Reads frames until the reply matching `ref_` on our topic arrives,
254    /// buffering any other events we recognize along the way.
255    async fn await_reply(&mut self, ref_: &str) -> Result<Value, ScribeError> {
256        loop {
257            let (_, frame_ref, topic, event, payload) = self.recv_frame().await?;
258            if topic != self.topic {
259                continue;
260            }
261            if event == "phx_reply" && frame_ref.as_deref() == Some(ref_) {
262                let reply: ReplyPayload = serde_json::from_value(payload)?;
263                return match reply.status.as_str() {
264                    "ok" => Ok(reply.response),
265                    _ => Err(map_channel_error(reply.response)),
266                };
267            }
268            if let Some(event) = parse_event(&event, &payload) {
269                self.pending.push_back(event);
270            }
271        }
272    }
273}
274
275async fn send_frame(
276    ws: &mut WsStream,
277    join_ref: Option<&str>,
278    ref_: &str,
279    topic: &str,
280    event: &str,
281    payload: Value,
282) -> Result<(), ScribeError> {
283    let frame: RawFrame = (
284        join_ref.map(str::to_string),
285        Some(ref_.to_string()),
286        topic.to_string(),
287        event.to_string(),
288        payload,
289    );
290    let text = serde_json::to_string(&frame)?;
291    ws.send(Message::text(text))
292        .await
293        .map_err(|e| ScribeError::WebSocket(Box::new(e)))?;
294    Ok(())
295}
296
297fn parse_event(event: &str, payload: &Value) -> Option<ChannelEvent> {
298    match event {
299        "status" => {
300            let format = OutputFormat::parse(payload.get("format")?.as_str()?)?;
301            let stage = serde_json::from_value(payload.get("stage")?.clone()).ok()?;
302            let progress = payload.get("progress")?.as_f64()?;
303            Some(ChannelEvent::Status {
304                format,
305                stage,
306                progress,
307            })
308        }
309        "chunk" => Some(ChannelEvent::Chunk {
310            content: payload.get("content")?.as_str()?.to_string(),
311        }),
312        "conversion_complete" => Some(ChannelEvent::ConversionComplete {
313            format: OutputFormat::parse(payload.get("format")?.as_str()?)?,
314            output_id: payload.get("output_id")?.as_str()?.to_string(),
315        }),
316        "error" => Some(ChannelEvent::Error {
317            reason: payload.get("reason")?.as_str()?.to_string(),
318        }),
319        "password_required" => Some(ChannelEvent::PasswordRequired),
320        _ => None,
321    }
322}
323
324fn map_channel_error(payload: Value) -> ScribeError {
325    let Ok(err) = serde_json::from_value::<ErrorReason>(payload) else {
326        return ScribeError::ChannelClosed;
327    };
328    // These channel error frames don't carry a `message` field from the
329    // server yet, so the friendly text here is a client-side fallback for
330    // now (matches the text these codes have always shown) — everything
331    // that already gets a server `message` (HTTP API responses, OAuth
332    // token errors) uses that instead; see error_for_status_or_json_error.
333    match err.reason.as_str() {
334        "not_found" => ScribeError::NotFound {
335            message: "We couldn't find that document.".to_string(),
336        },
337        "forbidden" => ScribeError::Forbidden {
338            message: "You don't have permission to access that document.".to_string(),
339        },
340        "conversion_in_progress" => ScribeError::ConversionInProgress {
341            message: "A conversion is already in progress for this document.".to_string(),
342        },
343        "rate_limited" => ScribeError::RateLimited {
344            message: "Rate limited, try again shortly.".to_string(),
345        },
346        "password_required" => ScribeError::PasswordRequired {
347            message: "This document is password-protected. Enter its password to continue."
348                .to_string(),
349        },
350        "needs_purchase" => ScribeError::NeedsPurchase {
351            message: "You need to purchase more pages to do that.".to_string(),
352            purchase_url: err.purchase_url.unwrap_or_default(),
353        },
354        _ => ScribeError::Channel {
355            message: "Something went wrong. Please try again.".to_string(),
356        },
357    }
358}