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