docs: fill in some autoconnect TODO docs (#410)

and add README badges

SYNC-3742

README.md

@@ -1,5 +1,8 @@
-[![Build](https://travis-ci.org/mozilla-services/autopush-rs.svg?branch=master)](https://travis-ci.org/mozilla-services/autopush-rs)
-[![License: MPL 2.0](https://img.shields.io/badge/License-MPL%202.0-brightgreen.svg)](https://opensource.org/licenses/MPL-2.0)
+[![License: MPL 2.0][mpl-svg]][mpl]
+[![Build Status][circleci-badge]][circleci]
+[![docs][docs-badge]][docs]
+[![autoconnect API][autoconnect-API-docs-badge]][autoconnect-API-docs]
+[![autoendpoint API][autoendpoint-API-docs-badge]][autoendpoint-API-docs]
 [![Connect to Matrix via the Riot webapp][matrix-badge]][matrix]
 
 # Autopush-rs
@@ -10,11 +13,9 @@ This is the fourth generation of the Mozilla Web Push server. It currently suppo
 and support for
 [Megaphone](https://github.com/mozilla-services/megaphone) broadcast.
 
-Please consult the [autopush
-documentation](http://autopush.readthedocs.io/en/latest/index.html)
-for information about how this server works, as well as any [error
-messages](http://autopush.readthedocs.io/en/latest/http.html#error-codes)
-you may see when sending push messages to our server.
+Please consult the [autopush documentation][docs] for information
+about how this server works, as well as any [error messages] you may
+see when sending push messages to our server.
 
 MDN has information about [how to use
 WebPush](https://developer.mozilla.org/en-US/docs/Web/API/Push_API).
@@ -24,9 +25,6 @@ through the source, only public structures are rendered automatically.
 For those curious about the inner workings, You may wish to read the
 code files directly.
 
-[matrix-badge]: https://img.shields.io/badge/chat%20on%20[m]-%23push%3Amozilla.org-blue
-[matrix]: https://chat.mozilla.org/#/room/#push:mozilla.org
-
 ## Debugging on Mobile
 
 Mobile devices can specify the Push Server URL via the "[secret settings](https://github.com/mozilla-mobile/fenix/wiki/%22Secret-settings%22-debug-menu-instructions)".
@@ -37,3 +35,17 @@ The secret settings can be activatedby following [these instructions](https://gi
 **Sync Debug** from the the mobile **Settings** menu, and specify the **Custom Push server** URL.
 
 **NOTE:** the default Push server url is `wss://push.services.mozilla.com/`
+
+[mpl-svg]: https://img.shields.io/badge/License-MPL%202.0-blue.svg
+[mpl]: https://opensource.org/licenses/MPL-2.0
+[circleci-badge]: https://circleci.com/gh/mozilla-services/autopush-rs.svg?style=shield
+[circleci]: https://circleci.com/gh/mozilla-services/autopush-rs
+[autoconnect-API-docs-badge]: https://img.shields.io/badge/autoconnect%20API%20-%20docs%20-%20light%20green
+[autoconnect-API-docs]: https://mozilla-services.github.io/autopush-rs/api/autoconnect/
+[autoendpoint-API-docs-badge]: https://img.shields.io/badge/autoendpoint%20API%20-%20docs%20-%20light%20green
+[autoendpoint-API-docs]: https://mozilla-services.github.io/autopush-rs/api/autoendpoint/
+[docs-badge]: https://github.com/mozilla-services/autopush-rs/actions/workflows/publish_docs.yml/badge.svg
+[docs]: https://mozilla-services.github.io/autopush-rs/
+[matrix-badge]: https://img.shields.io/badge/chat%20on%20[m]-%23push%3Amozilla.org-blue
+[matrix]: https://chat.mozilla.org/#/room/#push:mozilla.org
+[error messages]: https://mozilla-services.github.io/autopush-rs/errors.html

autoconnect/autoconnect-ws/autoconnect-ws-sm/src/identified/mod.rs

@@ -127,6 +127,11 @@ impl WebPushClient {
         Ok((client, smsgs))
     }
 
+    /// Return a reference to `AppState`'s `Settings`
+    pub fn app_settings(&self) -> &Settings {
+        &self.app_state.settings
+    }
+
     /// Connect this `WebPushClient` to the `ClientRegistry`
     ///
     /// Returning a `Stream` of `ServerNotification`s from the `ClientRegistry`
@@ -264,11 +269,6 @@ impl WebPushClient {
             .tags
             .insert("ua_browser_ver".to_owned(), ua_info.browser_version);
     }
-
-    /// Return a reference to `AppState`'s `Settings`
-    pub fn app_settings(&self) -> &Settings {
-        &self.app_state.settings
-    }
 }
 
 /// Ensure an existing user's record is valid, returning its `ClientFlags`
@@ -373,8 +373,24 @@ struct AckState {
     unacked_direct_notifs: Vec<Notification>,
     /// List of unAck'd sent notifications from storage
     unacked_stored_notifs: Vec<Notification>,
-    /// Id of the last previously unAck'd, stored transmission
-    /// TODO: better docs
+    /// Either the `current_timestamp` value in storage (returned from
+    /// `fetch_messages`) or the last unAck'd timestamp Message's
+    /// `sortkey_timestamp` (returned from `fetch_timestamp_messages`).
+    ///
+    /// This represents the "pointer" to the beginning (more specifically the
+    /// record preceeding the beginning used in a Greater Than query) of the
+    /// next batch of timestamp Messages.
+    ///
+    /// Thus this value is:
+    ///
+    /// a) initially None, then
+    ///
+    /// b) retrieved from `current_timestamp` in storage then passed as the
+    /// `timestamp` to `fetch_timestamp_messages`. When all of those timestamp
+    /// Messages are Ack'd, this value's then
+    ///
+    /// c) written back to `current_timestamp` in storage via
+    /// `increment_storage`
     unacked_stored_highest: Option<u64>,
 }
 

autoconnect/autoconnect-ws/autoconnect-ws-sm/src/identified/on_client_msg.rs

@@ -272,7 +272,10 @@ impl WebPushClient {
     /// Post process the Client succesfully Ack'ing all Push Notifications it's
     /// been sent.
     ///
-    /// TODO: more docs
+    /// Notifications are read in small batches (approximately 10). We wait for
+    /// the Client to Ack every Notification in that batch (invoking this
+    /// method) before proceeding to read the next batch (or potential other
+    /// actions such as `reset_uaid`).
     async fn post_process_all_acked(&mut self) -> Result<Vec<ServerMessage>, SMError> {
         trace!("▶️ WebPushClient:post_process_all_acked");
         let flags = &self.flags;

autoconnect/autoconnect-ws/autoconnect-ws-sm/src/identified/on_server_notif.rs

@@ -164,7 +164,14 @@ impl WebPushClient {
 
     /// Read a chunk (max count 10 returned) of Notifications from storage
     ///
-    /// TODO: document topic vs timestamp messages
+    /// This alternates between reading Topic Notifications and Timestamp
+    /// Notifications which are stored separately in storage.
+    ///
+    /// Topic Messages differ in that they replace pending Notifications with
+    /// new ones if they have matching Topic names. They are used when a sender
+    /// desires a scenario where multiple Messages sent to an offline device
+    /// result in the user only seeing the latest Message when the device comes
+    /// online.
     async fn do_check_storage(&self) -> Result<CheckStorageResponse, SMError> {
         trace!("🗄️ WebPushClient::do_check_storage");
         let timestamp = self.ack_state.unacked_stored_highest;
@@ -232,8 +239,11 @@ impl WebPushClient {
         })
     }
 
-    /// Update the user's last message read timestamp (for timestamp messages)
-    /// TODO: more docs
+    /// Update the user's last Message read timestamp (for timestamp Messages)
+    ///
+    /// Called when a Client's Ack'd all timestamp messages sent to it to move
+    /// the timestamp Messages' "pointer". See
+    /// `AckState::unacked_stored_highest` for further information.
     pub(super) async fn increment_storage(&mut self) -> Result<(), SMError> {
         trace!(
             "🗄️ WebPushClient::increment_storage: unacked_stored_highest: {:?}",

autoconnect/autoconnect-ws/autoconnect-ws-sm/src/unidentified.rs

@@ -39,6 +39,11 @@ impl UnidentifiedClient {
         UnidentifiedClient { ua, app_state }
     }
 
+    /// Return a reference to `AppState`'s `Settings`
+    pub fn app_settings(&self) -> &Settings {
+        &self.app_state.settings
+    }
+
     /// Handle a WebPush `ClientMessage` sent from the user agent over the
     /// WebSocket for this user
     ///
@@ -153,7 +158,7 @@ impl UnidentifiedClient {
     }
 
     /// Initialize `Broadcast`s for a new `WebPushClient`
-    pub async fn broadcast_init(
+    async fn broadcast_init(
         &self,
         broadcasts: &[Broadcast],
     ) -> (BroadcastSubs, HashMap<String, BroadcastValue>) {
@@ -170,11 +175,6 @@ impl UnidentifiedClient {
         }
         (broadcast_subs, response)
     }
-
-    /// Return a reference to `AppState`'s `Settings`
-    pub fn app_settings(&self) -> &Settings {
-        &self.app_state.settings
-    }
 }
 
 /// Result of a User lookup for a Hello message

autoconnect/autoconnect-ws/src/handler.rs

@@ -114,7 +114,24 @@ async fn unidentified_ws(
 }
 
 /// The identified `WebPushClient` handler
-/// TODO: docs
+///
+/// The main core of autoconnect, this is a select loop of actions for a
+/// potentially long lived connection to a Client.
+///
+/// The loop waits on 3 different inputs:
+///
+/// - msg_stream: Stream of WebPush Protocol `ServerMessage`s (from the Client
+/// to the Server) that are passed to `WebPushClient::on_client_msg`.
+///
+/// - snotif_stream: Stream of `ServerNotification`s, most of which are
+/// generated by autoendpoint, that are passed to
+/// `WebPushClient::on_server_notif`.
+///
+/// - ping_manager: A multi-purpose timer that ticks when either a WebSocket
+/// Ping (or WebPush Broadcast) should be sent to the Client or when we time
+/// out the Client for not responding to a previous Ping in time. The Ping
+/// encourages the connection to keep alive (it's more likely to be dropped if
+/// completely idle) and aids in detecting Clients that are no longer connected
 async fn identified_ws(
     client: &mut WebPushClient,
     smsgs: impl IntoIterator<Item = ServerMessage>,