engine_observables_api/
loading.rs

1/* This Source Code Form is subject to the terms of the Mozilla Public
2 * License, v. 2.0. If a copy of the MPL was not distributed with this
3 * file, You can obtain one at https://mozilla.org/MPL/2.0/. */
4
5//! Request/response state for the active session — redirects, MIME,
6//! TLS summary, cache origin, errors.
7//!
8//! Cf. Hekate doc §"Loading/Network Plane". Lanes (or their protocol
9//! adapters) emit loading events; Hekate records the normalized
10//! snapshot per session; the host displays status / error / progress.
11
12use malloc_size_of_derive::MallocSizeOf;
13use serde::{Deserialize, Serialize};
14
15/// Common-minimum loading-state queries. Implemented by Hekate's
16/// per-session snapshot — exposed to the host for chrome (URL bar,
17/// security indicator, loading spinner) and to Apparatus for
18/// debugging.
19pub trait LoadingQuery {
20    fn state(&self) -> LoadingState;
21    fn progress(&self) -> Option<LoadProgress>;
22    /// Final URL after redirects, if a load has completed enough to
23    /// identify a final source.
24    fn final_url(&self) -> Option<&str>;
25    /// Redirect chain (in order). Empty if no redirects occurred.
26    fn redirect_chain(&self) -> &[String];
27    /// MIME / Content-Type of the response body.
28    fn mime(&self) -> Option<&str>;
29    /// TLS handshake summary, if the load used HTTPS / TLS-wrapped
30    /// protocol.
31    fn tls_summary(&self) -> Option<&TlsSummary>;
32    /// Whether the response came from cache, missed, or isn't
33    /// cacheable.
34    fn cache_origin(&self) -> CacheOrigin;
35    /// Protocol/network/certificate error, if the load failed.
36    fn error(&self) -> Option<&LoadError>;
37}
38
39#[derive(
40    Clone, Copy, Debug, Default, Deserialize, Eq, Hash, MallocSizeOf, PartialEq, Serialize,
41)]
42pub enum LoadingState {
43    /// No load in progress yet; session created but request not sent.
44    #[default]
45    Pending,
46    /// Request sent; response headers may or may not have arrived.
47    InProgress,
48    /// Response fully received (or fully rendered if the lane does
49    /// stream-as-render).
50    Done,
51    /// Load terminated by error before completion.
52    Failed,
53}
54
55/// Progress signal: bytes received vs (optionally) total bytes.
56#[derive(Clone, Copy, Debug, Default, Deserialize, MallocSizeOf, PartialEq, Serialize)]
57pub struct LoadProgress {
58    pub bytes_received: u64,
59    /// Total bytes if Content-Length / equivalent is known, else
60    /// `None` (e.g., chunked encoding without a total).
61    pub bytes_total: Option<u64>,
62}
63
64/// Minimal TLS handshake summary. Lane-specific protocols (Gemini,
65/// Tor onion) may extend this in their own observables.
66#[derive(Clone, Debug, Default, Deserialize, MallocSizeOf, PartialEq, Serialize)]
67pub struct TlsSummary {
68    pub protocol: String, // e.g., "TLS 1.3"
69    pub cipher_suite: String,
70    /// Whether the cert chain validated against the trust store.
71    pub validated: bool,
72    /// Hostname certificate is valid for (the leaf cert's CN/SAN).
73    pub host: String,
74}
75
76#[derive(
77    Clone, Copy, Debug, Default, Deserialize, Eq, Hash, MallocSizeOf, PartialEq, Serialize,
78)]
79pub enum CacheOrigin {
80    /// Response came from cache (HTTP cache, lane-specific cache).
81    CacheHit,
82    /// Cache had no usable entry; went to network.
83    #[default]
84    CacheMiss,
85    /// Response carried `Cache-Control: no-store` or equivalent.
86    NotCacheable,
87}
88
89/// Categorized load error. Concrete shape per error kind kept
90/// intentionally narrow — consumers usually only need the kind +
91/// summary for display, not deep structured access.
92#[derive(Clone, Debug, Deserialize, MallocSizeOf, PartialEq, Serialize)]
93pub struct LoadError {
94    pub kind: LoadErrorKind,
95    /// Human-readable summary. Lane-specific.
96    pub message: String,
97}
98
99#[derive(
100    Clone, Copy, Debug, Default, Deserialize, Eq, Hash, MallocSizeOf, PartialEq, Serialize,
101)]
102pub enum LoadErrorKind {
103    /// Couldn't reach the host (DNS, connection refused, timeout).
104    Network,
105    /// HTTPS / TLS handshake failed (bad cert, hostname mismatch,
106    /// protocol downgrade).
107    TlsHandshake,
108    /// HTTP status >= 400 or protocol-specific equivalent.
109    ServerError,
110    /// Response body malformed for the declared MIME / protocol.
111    Decoding,
112    /// Other / unclassified.
113    #[default]
114    Other,
115}
engine_observables_api/loading.rs

engine_observables_api/
loading.rs
