Add more documentation, minor code cleanups.

src/fleck_core.rs

@@ -1,6 +1,12 @@
 //! This module contains the core services (and channel definitions) that make up a `fleck` node.
 //!
-//! Currently, the following externally-accessible services are added by default:
+//! The following services are probably where you want to start if you're learning how `fleck`
+//! works:
+//! - [`NodeService`]: Representations of nodes inside the fleck network
+//! - [`MessageService`]: Serialization and deserialization of messages
+//! - [`PeerDiscovery`](discovery/struct.PeerDiscovery.html): Programmatic interface for informing `fleck` of a new peer
+//! - [`LocalDiscovery`](discovery/struct.LocalDiscovery.html): Local discovery by multicast or
+//! other broadcast communication mechanisms.
 
 pub mod crypto;
 pub mod discovery;
@@ -12,8 +18,9 @@ pub mod routing;
 
 pub use msg::{Message, MessageChannel, MessageParams, MessageService};
 pub use node::{Node, NodeRegistrationChannel, NodeService};
-pub use peer::{Peer, PeerService};
+pub use peer::Peer;
 
+#[doc(hidden)]
 pub mod channel_tags {
     pub struct SendPacketTag {}
     pub struct ReceivePacketTag {}
@@ -28,6 +35,8 @@ pub enum SendOrder {
     Encrypt,
     Dispatch,
 }
+
+/// Outgoing packet dispatch processing channel. See [`SendOrder`] for the stages.
 pub type SendPacketChannel = (channel_tags::SendPacketTag, msg::Message, SendOrder);
 
 #[derive(PartialEq, PartialOrd, Clone)]
@@ -39,6 +48,7 @@ pub enum ReceiveOrder {
     Parse,
     Dispatch,
 }
+/// Incoming packet processing channel. If you're trying to handle an incoming message, this probably _isn't_ the one you're looking for, see [`msg::MessageChannel`] instead.
 pub type ReceivePacketChannel = (channel_tags::ReceivePacketTag, msg::Message, ReceiveOrder);
 
 /// Minor ticks (roughly once per second): for retries, status updates, etc.

src/fleck_core/crypto.rs

@@ -7,6 +7,7 @@ use aes_gcm::{
 pub use ed25519_dalek::{Keypair, Signature, Signer};
 
 use crate::prelude::*;
+use fleck_core::msg::MessageParams;
 
 pub enum TrustLevel {
     Unknown,
@@ -323,12 +324,13 @@ impl EncryptionService {
         let send = || {
             log::trace!("sending KeyExchange message");
             self.api.queue::<fleck_core::SendPacketChannel>(
-                fleck_core::msg::Message::build(KeyExchange {
+                KeyExchange {
                     pubkey: self
                         .api
                         .with_service(|ns: &fleck_core::NodeService| ns.self_node().pubkey().0),
                     key: x25519_dalek::PublicKey::from(&secret),
-                })
+                }
+                .into_message()
                 .with_node(with.clone()),
             );
         };

src/fleck_core/discovery.rs

@@ -1,4 +1,4 @@
-use crate::prelude::*;
+use crate::{fleck_core::MessageParams, prelude::*};
 
 use serde::{Deserialize, Serialize};
 use std::{cell::RefCell, collections::HashSet, rc::Rc};
@@ -75,12 +75,13 @@ impl LocalDiscovery {
 
     fn process_major_tick(&self, _: &mut ()) {
         for peer in self.targets.borrow().iter() {
-            let msg = fleck_core::msg::Message::build(DiscoveryMsg {
+            let msg = DiscoveryMsg {
                 pkey: self.api.with_service(|ns: &fleck_core::NodeService| {
                     ns.self_node().pubkey().to_owned()
                 }),
                 ttl: 1,
-            })
+            }
+            .into_message()
             .with_peer(peer.clone());
 
             self.api.queue::<fleck_core::SendPacketChannel>(msg);
@@ -125,6 +126,11 @@ impl PeerDiscovery {
         Some(msg)
     }
 
+    /// Introduce a new peer into the `fleck` network.
+    ///
+    /// This function takes a [`fleck_core::Peer`] instance, which may be difficult to get ahold of
+    /// in some circumstances. See [`fleck_core::io`] for details, but generally, you can retrieve
+    /// a `Peer` from whatever [`fleck_core::io::FdHandler`] is providing communication.
     pub fn new_peer(&self, peer: fleck_core::Peer) {
         let mut known = self.known.borrow_mut();
         known.insert(peer.clone());
@@ -132,12 +138,13 @@ impl PeerDiscovery {
         log::trace!("given new peer!");
 
         self.api.queue::<fleck_core::SendPacketChannel>(
-            fleck_core::msg::Message::build(DiscoveryMsg {
+            DiscoveryMsg {
                 pkey: self
                     .api
                     .with_service(|ns: &fleck_core::NodeService| ns.self_node().pubkey().clone()),
                 ttl: 2,
-            })
+            }
+            .into_message()
             .with_peer(peer),
         );
     }

src/fleck_core/io.rs

@@ -11,10 +11,15 @@ use crate::prelude::*;
 mod timerfd;
 pub use self::timerfd::TimerFdBuilder;
 mod udp;
-pub use udp::UdpSocketBuilder;
+pub use udp::{UdpSocketBuilder, UdpSocketRef};
 mod unix;
-pub use unix::UnixSocketBuilder;
+pub use unix::{UnixSocketBuilder, UnixSocketRef};
 
+/// This struct is only of interest to those implementing custom [`FdHandler`] instances for their
+/// own applications.
+///
+/// This is a lightweight wrapper around the internal `poll(2)` calls to change what events your
+/// [`FdHandler`] is interested in listening for.
 pub struct InterestRegistration {
     poll: Rc<RefCell<mio::Poll>>,
     token: mio::Token,
@@ -35,16 +40,35 @@ impl InterestRegistration {
     }
 }
 
+/// A file-descriptor based I/O subsystem. Generally not of interest unless you're implementing a
+/// custom I/O subsystem for your particular application of `fleck`.
 pub trait FdHandler {
+    /// Retrieve the [`InterestRegistration`] associated with this `FdHandler`.
     fn interest(&self) -> &InterestRegistration;
+    /// The `poll(2)` has indicated that the file descriptor is ready to be read from.
+    ///
+    /// One subtlety of this function is the `rc` parameter, where `rc.as_ref() == self` --- which
+    /// at first seems nonsensical.  However, [`Peer`](../peer/struct.Peer.html) instances require a `Rc<FdHandler>`, which
+    /// is not otherwise available to an implementation of this function.
     fn ready_read(&self, rc: &Rc<dyn FdHandler>);
+    /// The `poll(2)` has indicated that the file descriptor is ready to be written to. Like
+    /// [`Self::ready_read`], the `rc` parameter is given in case a `Peer` must be constructed in this
+    /// function.
     fn ready_write(&self, rc: &Rc<dyn FdHandler>);
+    /// Handle a message that has been dispatched to this `FdHandler` by means of a `Peer`
+    /// reference.
     fn dispatch(&self, msg: super::msg::Message);
 }
 
-pub struct HandlerTag;
-pub type NewHandlerChannel = (HandlerTag, Rc<dyn FdHandler>);
+struct HandlerTag;
+type NewHandlerChannel = (HandlerTag, Rc<dyn FdHandler>);
 
+/// Service that 'handles' all the nitty-gritty details of I/O by farming off into a [`FdHandler`]
+/// instance, such as a `UdpSocket` (see [`UdpSocketBuilder`]) or `TimerFd` (see
+/// [`TimerFdBuilder`]).
+///
+/// Generally, this service will be set up during startup and then not configured past then. One
+/// exception to this might be if you have new peer connection details entered during runtime.
 pub struct IOService {
     api: Rc<crate::API>,
     poll: Rc<RefCell<mio::Poll>>,

src/fleck_core/io/timerfd.rs

@@ -1,6 +1,7 @@
 use super::{fleck_core, FdHandler, IOService, InterestRegistration};
 use std::{os::unix::prelude::AsRawFd, rc::Rc};
 
+/// Build a `timerfd` instance to receive regular updates in a [`crate::Service`]
 #[derive(Default)]
 pub struct TimerFdBuilder {
     interval: Option<std::time::Duration>,

src/fleck_core/io/udp.rs

@@ -7,6 +7,7 @@ use std::{
     rc::Rc,
 };
 
+/// Builds a UDP socket to interact with an [`IOService`].
 #[derive(Default)]
 pub struct UdpSocketBuilder {
     bind: Option<std::net::SocketAddr>,
@@ -60,6 +61,8 @@ impl UdpSocketBuilder {
     }
 }
 
+/// Runtime wrapper around a UDP socket's functionality that a `fleck` node might be interested in
+/// past node setup.
 pub struct UdpSocketRef {
     sock: Rc<UdpSocket>,
 }

src/fleck_core/io/unix.rs

@@ -11,6 +11,7 @@ use mio::net::{UnixListener, UnixStream};
 
 use super::{FdHandler, IOService, InterestRegistration};
 
+/// Builds a Unix socket to interact with an [`IOService`].
 #[derive(Default)]
 pub struct UnixSocketBuilder {
     path: Option<String>,
@@ -43,6 +44,8 @@ impl UnixSocketBuilder {
     }
 }
 
+/// Runtime wrapper around a UNIX socket's functionality that a `fleck` node might be interested in
+/// past node setup.
 pub struct UnixSocketRef {
     sock: UnixSocket,
 }

src/fleck_core/msg.rs

@@ -11,10 +11,21 @@ use crate::prelude::*;
 
 const MESSAGE_MAGIC: u64 = 0x1234123412341234;
 
+/// Metadata about a message type.
 pub trait MessageParams: 'static {
     const NAME: &'static str;
     const ENCRYPTED: bool = true;
     const SIGNED: bool = false;
+
+    /// Helper wrapper around the [`Message::build`] function; you don't need to implement this,
+    /// it's only here for convenience at message construction sites.
+    fn into_message(self) -> Message
+    where
+        Self: Serialize,
+        Self: Sized,
+    {
+        Message::build(self)
+    }
 }
 
 #[derive(Clone, Copy, Debug)]
@@ -114,7 +125,33 @@ impl<T: 'static + Serialize + MessageParams> From<T> for Message {
     }
 }
 
+#[doc(hidden)]
 pub struct MessageChannelTag;
+
+/// Probably the most-commonly used family of channels in `fleck_core`: incoming message
+/// distribution!
+///
+/// A minimal example of a service that listens for a packet on this channel might be:
+///
+/// ```rust
+/// # use fleck::prelude::*;
+/// # use std::rc::Rc;
+/// # #[derive(Default, Debug, serde::Serialize, serde::Deserialize)]
+/// # struct ExampleMessageType {}
+/// #[derive(Default)]
+/// struct ExampleService;
+/// impl ExampleService {
+///     fn handle(&self, msg: (fleck_core::msg::Metadata, ExampleMessageType)) {
+///         // TODO: process the message
+///     }
+/// }
+/// impl DefaultService for ExampleService {
+///     fn setup(self: &Rc<Self>, api: std::rc::Rc<fleck::API>) {
+///         api.channel::<fleck_core::MessageChannel<ExampleMessageType>>().sub_eat(self, Self::handle);
+///     }
+/// }
+///
+/// ```
 pub type MessageChannel<M> = (MessageChannelTag, (Metadata, M));
 
 type Deserializer = dyn Fn(&Message);

src/fleck_core/peer.rs

@@ -2,7 +2,7 @@
 //!
 //!
 
-use std::{cell::Cell, rc::Rc};
+use std::rc::Rc;
 
 use crate::prelude::*;
 
@@ -10,32 +10,18 @@ use crate::prelude::*;
 pub(crate) enum PeerAddress {
     Stream,
     Udp(std::net::SocketAddr),
-    Virtual,
+    #[allow(unused)]
+    UserAddress(Box<dyn std::any::Any>),
 }
 
 pub(crate) struct PeerData {
     pub(crate) io: Rc<dyn super::io::FdHandler>,
     pub(crate) address_info: PeerAddress,
-    sequence_number: Cell<u64>,
 }
 
 impl PeerData {
     pub(crate) fn new(io: Rc<dyn super::io::FdHandler>, address_info: PeerAddress) -> Self {
-        Self {
-            io,
-            address_info,
-            sequence_number: Cell::new(0),
-        }
-    }
-
-    pub(crate) fn next_sequence(&self) -> u64 {
-        let ret = self.sequence_number.get();
-        self.sequence_number.set(ret.wrapping_add(1));
-        ret
-    }
-
-    pub(crate) fn reset_sequence(&self, to: u64) {
-        self.sequence_number.set(to);
+        Self { io, address_info }
     }
 }
 
@@ -51,7 +37,9 @@ impl std::fmt::Debug for PeerData {
 /// The primary peer representation as used in `fleck`.
 ///
 /// This is deliberately an opaque type, to encourage writing transport-agnostic code as much as
-/// possible. Treat as a black box unless you really have to not.
+/// possible. Treat as a black box unless you _really_ have to not for some reason; in that case
+/// you probably should change the [`FdHandler`](../io/trait.FdHandler.html) implementation
+/// instead.
 #[derive(Clone, Debug)]
 pub struct Peer {
     pub(crate) data: Rc<PeerData>,
@@ -74,7 +62,7 @@ impl Eq for Peer {
 }
 
 #[derive(Default)]
-pub struct PeerService {}
+pub(crate) struct PeerService {}
 
 impl DefaultService for PeerService {
     fn setup(self: &Rc<Self>, api: Rc<crate::API>) {

src/fleck_core/routing.rs

@@ -8,6 +8,17 @@ use crate::fleck_core;
 
 use fleck_core::crypto::PublicKey;
 
+use super::MessageParams;
+
+#[derive(Clone, PartialEq, Debug)]
+struct RoutingTable {
+    peers: HashMap<PublicKey, HashSet<fleck_core::Peer>>,
+}
+
+impl RoutingTable {
+    fn update_with(&mut self, other: &Self) {}
+}
+
 pub struct PacketRoutingService {}
 
 impl crate::Service for PacketRoutingService {
@@ -71,16 +82,17 @@ impl RoutingTableService {
     fn ask_for_updates(&self, _: &mut ()) {
         // TODO: ask each peer for what their known peers are
         // FUTURE TODO: stagger these requests at random offsets
-        for node in self
+        let peers = self
             .api
-            .with_service(|ns: &fleck_core::NodeService| ns.peers())
-        {
-            self.api
-                .queue::<fleck_core::SendPacketChannel>(fleck_core::msg::Message::build(
-                    RoutingTableRequest {
-                        known_generation: None,
-                    },
-                ));
+            .with_service(|ns: &fleck_core::NodeService| ns.peers());
+        for node in peers {
+            self.api.queue::<fleck_core::SendPacketChannel>(
+                RoutingTableRequest {
+                    known_generation: None,
+                }
+                .into_message()
+                .with_node(node),
+            );
         }
     }
 }