Skip to main content

scribe_client/
channel.rs

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