Merge pull request #849 from mozilla-services/docs

docs: Update docs

autopush/router/apns2.py

@@ -34,7 +34,7 @@ def __init__(self, cert_file, key_file, topic,
         """Create the APNS client connector.
 
         The cert_file and key_file can be derived from the exported `.p12`
-        **Apple Push Services: *bundleID*** key contained in the **Keychain
+        **Apple Push Services: *bundleID* ** key contained in the **Keychain
         Access** application. To extract the proper PEM formatted data, you
         can use the following commands:
 

autopush/router/apnsrouter.py

@@ -24,6 +24,8 @@ def _connect(self, rel_channel, load_connections=True):
 
         :param rel_channel: Release channel name (e.g. Firefox. FirefoxBeta,..)
         :type rel_channel: str
+        :param load_connections: (used for testing)
+        :type load_connections: bool
 
         :returns: APNs to be stored under the proper release channel name.
         :rtype: apns.APNs
@@ -43,7 +45,16 @@ def _connect(self, rel_channel, load_connections=True):
             load_connections=load_connections)
 
     def __init__(self, ap_settings, router_conf, load_connections=True):
-        """Create a new APNS router and connect to APNS"""
+        """Create a new APNS router and connect to APNS
+
+        :param ap_settings: Configuration settings
+        :type ap_settings: autopush.settings.AutopushSettings
+        :param router_conf: Router specific configuration
+        :type router_conf: dict
+        :param load_connections: (used for testing)
+        :type load_connections: bool
+
+        """
         self.ap_settings = ap_settings
         self._base_tags = []
         self.apns = dict()
@@ -58,7 +69,7 @@ def register(self, uaid, router_data, app_id, *args, **kwargs):
         """Register an endpoint for APNS, on the `app_id` release channel.
 
         This will validate that an APNs instance token is in the
-        ``router_data``,
+        `router_data`,
 
         :param uaid: User Agent Identifier
         :type uaid: str

autopush/settings.py

@@ -349,7 +349,7 @@ def parse_endpoint(self, token, version="v1", ckey_header=None,
         :param token: The obscured subscription data.
         :param version: This is the API version of the token.
         :param ckey_header: the Crypto-Key header bearing the public key
-        (from Crypto-Key: p256ecdsa=)
+            (from Crypto-Key: p256ecdsa=)
         :param auth_header: The Authorization header bearing the VAPID info
 
         :raises ValueError: In the case of a malformed endpoint.

docs/api.rst

@@ -10,7 +10,6 @@ documentation is organized alphabetically by module name.
    :maxdepth: 1
 
    api/db
-   api/endpoint
    api/exceptions
    api/logging
    api/main

docs/api/router/apnsrouter.rst

@@ -10,3 +10,11 @@
     :special-members: __init__
     :private-members:
     :member-order: bysource
+
+.. automodule:: autopush.router.apns2
+
+.. autoclass:: APNSClient
+    :members:
+    :special-members: __init__
+    :private-members:
+    :member-order: bysource

docs/apns.rst

@@ -0,0 +1,103 @@
+Configuring for the APNS bridge
+===============================
+
+APNS requires a current Apple Developer License for the platform
+or platforms you wish to bridge to (e.g. iOS, desktop, etc.). Once
+that license has been acquired, you will need to create and export
+a valid `.p12` type key file. For this document, we will concentrate
+on creating an iOS certificate.
+
+Create the App ID
+-----------------
+
+First, you will need an Application ID. If you do not already have an
+application, you will need to `create an application ID <https://developer.apple.com/account/ios/identifier/bundle/create>`_.
+For an App ID to use Push Notifications, it must be created as an **Explicit App ID**.
+Please be sure that under "**App Services**" you select **Push Notifications**.
+Once these values are set, click on [Continue].
+
+Confirm that the app settings are as you desire and click [Register], or click [Back] and correct them.
+**Push Notifications** should appear as "Configurable".
+
+Create the Certificate
+----------------------
+
+Then `Create a new certificate <https://developer.apple.com/account/ios/certificate/create>`_.
+Select "Apple Push Notification service SSL" for either Development or Production, depending on
+intended usage of the certificate. "Development", in this case, means a certificate that will
+not be used by an application released for general public use, but instead only for personal
+or team development. This is also known as a "Sandbox" application and will require
+setting the "use_sandbox" flag. Once the preferred option is selected, click
+[Continue].
+
+Select the App ID that matches the Application that will use Push Notifications. Several
+Application IDs may be present, be sure to match the correct App ID. This will be the App ID which
+will act as the recipient bridge for Push Notifications. Select [Continue].
+
+Follow the on-screen instructions to generate a **CSR file**, click [Continue],
+and upload the CSR.
+
+Download the newly created *iOSTeam_Provisioning_Profile_.mobileprovision* keyset, and
+import it into your **KeyChain Access** app.
+
+Exporting the .p12 key set
+--------------------------
+
+In **KeyChain Access**, for the **login** keychain, in the **Certificates** category,
+you should find an **Apple Push Services: *your AppID*** certificate. Right click on
+this certificate and select *Export "Apple Push Services:"...*. Provide the file
+with a reasonably unique name, such as "Push_Production_APNS_Keys.p12", so that you can find it easily
+later. You may wish to secure these keys with a password.
+
+Converting .p12 to PEM
+----------------------
+
+You will need to convert the .p12 file to PEM format. *openssl* can perform
+these steps for you. A simple script you could use might be:
+
+.. code-block:: bash
+
+   #!/bin/bash
+   echo Converting $1 to PEM
+   openssl pkcs12 -in $1 -out $1_cert.pem -clcerts -nokeys
+   openssl pkcs12 -in $1 -out $1_key.pem -nocerts -nodes
+
+
+This will divide the p12 key into two components that can be read by the autopush application.
+
+Sending the APNS message
+------------------------
+
+The APNS post message contains JSON formatted data similar to the following:
+
+.. code-block:: json
+
+    {
+        "aps": {
+            "alert": "notification title",
+            "content_available": 1
+        },
+        "key": "value",
+        ...
+    }
+
+
+*aps* is reserved as a sub-dictionary. All other *key*: *value* slots are open.
+
+In addition, you must specify the following headers:
+
+* *apns-id*: A lowercase, dash formatted UUID for this message.
+
+* *apns-priority*: Either **10** for Immediate delivery or **5** for delayable delivery.
+
+* *apns-topic*: The bundle ID for the recipient application. This must match the bundle ID of the AppID used to create the *"Apple Push Services:..."* certificate. It usually has the format of `com.example.ApplicationName`.
+
+* *apns-expiration*: The timestamp for when this message should expire in UTC based seconds.  A zero ("0") means immediate expiration.
+
+Handling APNS responses
+-----------------------
+
+APNS returns a status code and an optional JSON block describing the error. A list of `these
+responses are provided in the APNS documentation <https://developer.apple.com/library/content/documentation/NetworkingInternet/Conceptual/RemoteNotificationsPG/CommunicatingwithAPNs.html>`_ (Note, Apple may change the document locaiton without warning. you may be able to search using `DeviceTokenNotForTopic <https://developer.apple.com/search/?q=DeviceTokenNotForTopic&type=Guides>`_ or similar error messages.)
+
+

docs/architecture.rst

@@ -194,7 +194,7 @@ After Identification:
    clients router table entry, proceed to step 2.
 2. Read notifications from prior month and send to client.
 
-   Once all acks are received for all the notifications for that month proceed
+   Once all ACKs are received for all the notifications for that month proceed
    to step 3.
 3. Copy the blank message entry of valid channels to the new month message
    table.
@@ -220,7 +220,7 @@ Push Characteristics
   notifications will be accepted for delivery (except in one edge case).
   In this state, the Push server will reply to the Endpoint with a 503 to
   indicate it cannot currently deliver the notification. Once the Push
-  server has received ack's for all sent notifications, new notifications
+  server has received ACKs for all sent notifications, new notifications
   can flow again, and a check of storage will be done if the Push server had
   to reply with a 503. The Endpoint will put the Notification in storage in
   this case.
@@ -259,7 +259,7 @@ Push Endpoint Length
 The Endpoint URL may seem excessively long. This may seem needless and
 confusing since the URL consists of the unique User Agent Identifier (UAID)
 and the Subscription Channel Identifier (CHID). Both of these are class 4
-Universially Unique Identifiers (UUID) meaning that an endpoint contains
+Universally Unique Identifiers (UUID) meaning that an endpoint contains
 256 bits of entropy (2 * 128 bits). When used in string format, these UUIDs
 are always in lower case, dashed format (e.g.
 "01234567-0123-abcd-0123-0123456789ab").

docs/glossary.rst

@@ -44,7 +44,7 @@ Glossary
        also be referred to as a :term:`Channel`
 
     UAID
-       The Push User Agent Regisration ID. Push assigns each remote recipient
+       The Push User Agent Registration ID. Push assigns each remote recipient
        (Firefox client) a unique identifier. These may occasionally be reset
        by the Push Service or the client.
 

docs/http.rst

@@ -40,7 +40,8 @@ Lexicon
    :{UAID}: The Push User Agent Registration ID
 
 Push assigns each remote recipient a unique identifier. {UAID}s are UUIDs in
-lower case, dashed format. (e.g. '01234567-abcd-abcd-abcd-012345678abc') This value is assigned during **Registration**
+lower case, dashed format. (e.g. '01234567-abcd-abcd-abcd-01234567abcd') This
+value is assigned during **Registration**
 
    :{CHID}: The :term:`Channel` Subscription ID
 
@@ -225,7 +226,7 @@ Update the message at the given `{message_id}`.
 
     .. note::
 
-        In the rare condition that the client is online, and has recieved
+        In the rare condition that the client is online, and has received
         the message but has not acknowledged it yet; then it is possible that
         the client will not get the updated message until reconnect. This
         should be considered a rare edge-case.
@@ -326,7 +327,7 @@ This call requires no Authorization header for first time use.
     .. note::
 
         If additional information is required for the bridge, it may be
-        included in the paramters as JSON elements. Currently, no additional
+        included in the parameters as JSON elements. Currently, no additional
         information is required.
 
 **Reply:**
@@ -380,7 +381,7 @@ we are updating existing information.
     .. note::
 
         If additional information is required for the bridge, it may be
-        included in the paramters as JSON elements. Currently, no additional
+        included in the parameters as JSON elements. Currently, no additional
         information is required.
 
 **Reply:**

docs/index.rst

@@ -22,8 +22,8 @@ the `Mozilla Push Service architecture diagram`_. This push service uses
 websockets to talk to Firefox, with a Push endpoint that implements the
 :term:`WebPush` standard for its :ref:`http` API.
 
-Autopush API's
-==============
+Autopush APIs
+=============
 
 For developers writing mobile applications in Mozilla, or web developers using
 Push on the web with Firefox.
@@ -135,7 +135,7 @@ Reference
 License
 =======
 
-``autopush`` is offered under the Apache License 2.0.
+``autopush`` is offered under the Mozilla Public License 2.0.
 
 .. _\#push: irc://irc.mozilla.org/push
 .. _Mozilla Push Service architecture diagram: http://mozilla-push-service.readthedocs.io/en/latest/#architecture

docs/releasing.rst

@@ -14,7 +14,7 @@ Versions
 Autopush uses a ``{major}.{minor}.{patch}`` version scheme, new ``{major}``
 versions are only issued if backwards compatibility is affected. Patch
 versions are used if a critical bug occurs after production deployment that
-requires a bugfix immediately.
+requires a bug fix immediately.
 
 Dev Releases
 ============

docs/running.rst

@@ -69,7 +69,7 @@ run both of the Autopush daemons. To generate one with the docker image:
 
 .. code-block:: bash
 
-    $ docker run -t -i bbangert/autopush autokey
+    $ docker run -t -i ~/autopush autokey
     Key = hkclU1V37Dnp-0DMF9HLe_40Nnr8kDTYVbo2yxuylzk=
 
 Store the key for later use (including the trailing ``=``).
@@ -91,7 +91,7 @@ By default, the following services will be exposed:
 
 ``ws://localhost:8080/`` - websocket server
 
-``http://localhost:8082/`` - HTTP Endoint Server (See :ref:`the HTTP API <http>`)
+``http://localhost:8082/`` - HTTP Endpoint Server (See :ref:`the HTTP API <http>`)
 
 You could set the ``CRYPTO_KEY`` as an environment variable, or setup a more
 thorough configuration using config files as documented below.
@@ -133,14 +133,14 @@ Configuration files can be located in:
 The three configuration files are:
 
 * *autopush_connection.ini* - contains options for use by the websocket handler.
-  This file's path can be specifed by the ``--config-connection`` option.
+  This file's path can be specified by the ``--config-connection`` option.
 
 * *autopush_shared.ini* - contains options shared between the connection and
   endpoint handler. This file's path can be specified by the ``--config-shared``
   option.
 
 * *autopush_endpoint.ini* - contains options for the HTTP handlers This file's
-  path can be specifed by the ``--config-endpoint`` option.
+  path can be specified by the ``--config-endpoint`` option.
 
 Sample Configurations
 ---------------------

docs/testing.rst

@@ -65,5 +65,5 @@ On Android, you can set ``dom.push.debug`` to enable debug logging of Push
 via ``adb logcat``.
 
 For desktop use, you can set ``dom.push.loglevel`` to ``"debug"``. This will
-log all push messagesto the Browser Console (Tools > Web Developer > Browser
+log all push messages to the Browser Console (Tools > Web Developer > Browser
 Console).