docspec_core/
traits.rs

1//! Core traits for event sources, sinks, and asset handles.
2
3/// A self-contained handle to a single embedded asset.
4///
5/// Returned by readers inside `ImageSource::Asset(Arc<dyn AssetHandle>)`.
6/// The handle carries everything needed to resolve content type and stream
7/// bytes — no external provider lookup is required.
8pub trait AssetHandle: Send + Sync + core::fmt::Debug {
9    /// MIME content type (e.g. `"image/png"`). `None` means unknown.
10    fn content_type(&self) -> Option<std::borrow::Cow<'_, str>>;
11
12    /// Stream the asset bytes to `writer`. Returns total bytes written.
13    ///
14    /// # Errors
15    /// Returns `io::Error` if the underlying source fails or the asset is
16    /// no longer accessible (e.g. ZIP entry vanished, mutex poisoned).
17    fn stream_to(&self, writer: &mut dyn std::io::Write) -> std::io::Result<u64>;
18
19    /// Opaque identifier used for `Debug` formatting and `PartialEq` on
20    /// `ImageSource::Asset`. Format is reader-defined (e.g. `"zip://word/media/image1.png"`).
21    fn asset_id(&self) -> &str;
22}
23
24/// Consumes a stream of [`crate::Event`]s to produce output.
25///
26/// Writers implement this trait to translate document events into a target
27/// format. Call [`EventSink::handle_event`] for each event in order, then
28/// call [`EventSink::finish`] to flush output and signal completion.
29///
30/// `finish` consumes `self` to prevent reuse after the stream has ended.
31pub trait EventSink {
32    /// Flush any buffered output and finalize the document.
33    ///
34    /// Consumes `self` to prevent further use after the stream ends.
35    ///
36    /// # Errors
37    ///
38    /// Returns an error if flushing or finalization fails.
39    fn finish(self) -> crate::Result<()>;
40
41    /// Process one event from the stream.
42    ///
43    /// Events must arrive in valid document order. Writers may assume the
44    /// stream is well-formed per the rules in [`crate::event`].
45    ///
46    /// # Errors
47    ///
48    /// Returns an error if the sink cannot process the event (write failure,
49    /// invalid format, resource exhaustion).
50    fn handle_event(&mut self, event: crate::Event) -> crate::Result<()>;
51}
52
53/// Produces a stream of [`crate::Event`]s from a document source.
54///
55/// The pull-based design gives the consumer control: only fetch events when
56/// ready to process them. This provides natural backpressure and constant
57/// memory usage regardless of document size.
58///
59/// Return `Ok(None)` to signal the end of the stream. Return `Err` for fatal
60/// errors that prevent further reading.
61pub trait EventSource {
62    /// Returns the next event from the stream, or `None` if the stream has ended.
63    ///
64    /// # Errors
65    ///
66    /// Returns an error if the source encounters a fatal problem (malformed
67    /// input, truncated stream, I/O failure). After an error, the stream is
68    /// considered terminated.
69    fn next_event(&mut self) -> crate::Result<Option<crate::Event>>;
70}
docspec_core/traits.rs

docspec_core/
traits.rs
