kitsune2_api/
kitsune.rs

1//! Kitsune2 top-level module related types.
2
3use crate::*;
4use std::sync::Arc;
5
6/// Handler for events coming out of Kitsune2.
7pub trait KitsuneHandler: 'static + Send + Sync + std::fmt::Debug {
8    /// A notification that a new listening address has been bound.
9    /// Peers should now go to this new address to reach this node.
10    fn new_listening_address(&self, this_url: Url) -> BoxFut<'static, ()> {
11        drop(this_url);
12        Box::pin(async move {})
13    }
14
15    /// A peer has disconnected from us. If they did so gracefully
16    /// the reason will be is_some().
17    fn peer_disconnect(&self, peer: Url, reason: Option<String>) {
18        drop((peer, reason));
19    }
20
21    /// Gather preflight data to send to a new opening connection.
22    /// Returning an Err result will close this connection.
23    ///
24    /// The default implementation sends an empty preflight message.
25    fn preflight_gather_outgoing(
26        &self,
27        peer_url: Url,
28    ) -> K2Result<bytes::Bytes> {
29        drop(peer_url);
30        Ok(bytes::Bytes::new())
31    }
32
33    /// Validate preflight data sent by a remote peer on a new connection.
34    /// Returning an Err result will close this connection.
35    ///
36    /// The default implementation ignores the preflight data,
37    /// and considers it valid.
38    fn preflight_validate_incoming(
39        &self,
40        peer_url: Url,
41        data: bytes::Bytes,
42    ) -> K2Result<()> {
43        drop(peer_url);
44        drop(data);
45        Ok(())
46    }
47
48    /// Kitsune would like to construct a space. Provide a handler.
49    fn create_space(
50        &self,
51        space: SpaceId,
52    ) -> BoxFut<'_, K2Result<space::DynSpaceHandler>>;
53}
54
55/// Trait-object [KitsuneHandler].
56pub type DynKitsuneHandler = Arc<dyn KitsuneHandler>;
57
58/// The top-level Kitsune2 api trait.
59pub trait Kitsune: 'static + Send + Sync + std::fmt::Debug {
60    /// Register the kitsune handler exactly once before invoking any other
61    /// api functions.
62    ///
63    /// This dependency injection strategy makes it possible for a struct
64    /// to both act as a Handler and contain the resulting Kitsune instance.
65    ///
66    /// Implementations should error if this is invoked more that once,
67    /// and should return errors for any other api invocations if this has
68    /// not yet been called.
69    fn register_handler(
70        &self,
71        handler: DynKitsuneHandler,
72    ) -> BoxFut<'_, K2Result<()>>;
73
74    /// List the active spaces.
75    fn list_spaces(&self) -> Vec<SpaceId>;
76
77    /// Get an existing space with the provided [SpaceId] or create
78    /// a new one.
79    fn space(&self, space: SpaceId) -> BoxFut<'_, K2Result<space::DynSpace>>;
80
81    /// Get a space, only if it exists.
82    fn space_if_exists(
83        &self,
84        space: SpaceId,
85    ) -> BoxFut<'_, Option<space::DynSpace>>;
86
87    /// Remove a space, if it exists.
88    ///
89    /// This will remove the space from the list of active spaces. The space will only shutdown
90    /// cleanly if all modules are careful about not holding references to the space and transport.
91    fn remove_space(&self, space: SpaceId) -> BoxFut<'_, K2Result<()>>;
92
93    /// Get the transport handle.
94    fn transport(&self) -> BoxFut<'_, K2Result<DynTransport>>;
95}
96
97/// Trait-object [Kitsune].
98pub type DynKitsune = Arc<dyn Kitsune>;
99
100/// A factory for constructing Kitsune instances.
101pub trait KitsuneFactory: 'static + Send + Sync + std::fmt::Debug {
102    /// Help the builder construct a default config from the chosen
103    /// module factories.
104    fn default_config(&self, config: &mut config::Config) -> K2Result<()>;
105
106    /// Validate configuration.
107    fn validate_config(&self, config: &config::Config) -> K2Result<()>;
108
109    /// Construct a space instance.
110    fn create(
111        &self,
112        builder: Arc<builder::Builder>,
113    ) -> BoxFut<'static, K2Result<DynKitsune>>;
114}
115
116/// Trait-object [KitsuneFactory].
117pub type DynKitsuneFactory = Arc<dyn KitsuneFactory>;
kitsune2_api/kitsune.rs

kitsune2_api/
kitsune.rs
