From 1d24486497c5bad20d74c9d065b07a83b192523c Mon Sep 17 00:00:00 2001 From: jrconlin Date: Wed, 20 Jun 2018 15:06:33 -0700 Subject: [PATCH] docs: update documentation * remove python references * a bit more verbose README Issue #7 --- README.md | 26 +++++++++++++++++++++++++- src/lib.rs | 34 ++++++++-------------------------- src/server/mod.rs | 2 +- 3 files changed, 34 insertions(+), 28 deletions(-) diff --git a/README.md b/README.md index a58fd8efd..56fb5b92b 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,27 @@ +[![Build](https://travis-ci.org/mozilla-services/autopush-rs.svg?branch=master)](https://travis-ci.org/mozilla-services/autopush-rs) +[![License: MPL 2.0]][MPL 2.0] [![Build Status]][travis] +[![Latest Version]][crates.io] [![Api Rustdoc]][rustdoc] + # Autopush-rs -Mozilla Push server built with Rust. +Mozilla Push server built with [Rust](https://rust-lang.org). + +This is the fourth generation of the Mozilla Web Push server. This is +a "work in progress", that currently supports websocket connections +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. + +MDN has information about [how to use +WebPush](https://developer.mozilla.org/en-US/docs/Web/API/Push_API) + +***Note*** while `rust-doc` style comments are used prolifically +through the source, only pubic structures are rendered automatically. +For those curious about the inner workings, You may wish to read the +code files directly. + diff --git a/src/lib.rs b/src/lib.rs index c5be8bfbd..cca5b9ef4 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -1,29 +1,14 @@ //! WIP: Implementation of Web Push ("autopush" as well) in Rust -//! -//! This crate currently provides an implementation of an asynchronous Web Push -//! server which is intended to be interfaced with from Python. The crate mostly -//! has a C API which is driven from `__init__.py` in Python and orchestrated -//! from Python. This is currently done to help ease the transition from the old -//! Python implementation to the new Rust implementation. Currently there's a -//! good bit of API calls to remote services still implemented in Python, but -//! the thinking is that over time these services will be rewritten in to Rust -//! and the Python codebase will shrink. -//! -//! In any case though, this'll focus mainly on the Rust bits rather than the -//! Python bits! It's worth nothing though that this crate is intended to be -//! used with `cffi` in Python, which is "seamlessly" worked with through the -//! `snaek` Python dependency. That basically just means that Python "headers" -//! for this Rust crate are generated automatically. +//! +//! This crate currently provides the connection node functionality for a Web +//! Push server, and is a replacement for the +//! [`autopush`](https://github.com/mozilla-services/autopush) server. The older +//! python handler still manages the HTTP endpoint calls, since those require +//! less overhead to process. Eventually, those functions will be moved to +//! rust as well. //! //! # High level overview //! -//! At 10,000 feet the general architecture here is that the main Python thread -//! spins up a Rust thread which actually does all the relevant I/O. The one -//! Rust thread uses a `Core` from `tokio-core` to perform all I/O and schedule -//! asynchronous tasks. The `tungstenite` crate is used to parse and manage the -//! WebSocket protocol, with `tokio_tungstenite` being a nicer wrapper for -//! futures-style APIs. -//! //! The entire server is written in an asynchronous fashion using the `futures` //! crate in Rust. This basically just means that everything is exposed as a //! future (similar to the concept in other languages) and that's how bits and @@ -33,10 +18,7 @@ //! webpush protocol (see `states.dot` at the root of this repository). Note //! that not all states are implemented yet, this is a work in progress! All I/O //! is managed by Rust and various state transitions are managed by Rust as -//! well. Movement between states happens typically as a result of calls into -//! Python. The various operations here will call into Python to do things like -//! db/HTTP requests and then the results are interpreted in Rust to progress -//! the state machine. +//! well. //! //! # Module index //! diff --git a/src/server/mod.rs b/src/server/mod.rs index 894944eb5..8bafaf192 100644 --- a/src/server/mod.rs +++ b/src/server/mod.rs @@ -220,7 +220,7 @@ pub struct Server { } impl Server { - /// Creates a new server handle to send to python. + /// Creates a new server handle used by Megaphone and other services. /// /// This will spawn a new server with the `opts` specified, spinning up a /// separate thread for the tokio reactor. The returned ShutdownHandles can