Add platform troubleshooting documentation and sample configuration d…

…etails (#154)

A customer had an issue where they were using sandbox push tokens with the production server. I don't blame them, as this doesn't seem to have been documented anywhere.

I've added the `platform` option to the sample config with some explanation, as well as a section in troubleshooting in case others fall down the same path.

While adding to the sample config, I realised that we would eventually end up duplicating nearly every option if we didn't deduplicate early, so that's what I did.

changelog.d/154.doc

@@ -0,0 +1 @@
+Add troubleshooting documentation and sample configuration about APNs pushkin's `platform` option.

docs/troubleshooting.md

@@ -126,6 +126,23 @@ Instead of configuring Sygnal with your APNs secrets, you need to configure
 Firebase with your APNs secrets, and Sygnal with your Firebase secrets.
 
 
+#### Common cause 3: Using sandbox tokens with the production APNs server
+
+Sygnal connects to the production APNs instance by default. This will return
+`400 BadDeviceToken` if you send it a token intended for the sandbox APNs
+server.
+
+Either use production tokens, or switch to the sandbox APNs server by setting:
+
+```
+com.example.myapp.ios:
+  type: apns
+  ...
+  platform: sandbox
+```
+
+in your sygnal config file.
+
 ### App doesn't receive notifications when inactive
 
 If you want your application to be woken up to be able to process APNs messages

sygnal.yaml.sample

@@ -199,30 +199,24 @@ metrics:
 # For the type, you may specify a fully-qualified Python classname if desired.
 #
 apps:
-  # This is an example APNs push configuration using certificate authentication.
+  # This is an example APNs push configuration
   #
   #com.example.myapp.ios:
   #  type: apns
-  #  certfile: com.example.myApp_prod_APNS.pem
   #
-  #  # This is the maximum number of in-flight requests *for this pushkin*
-  #  # before additional notifications will be failed.
-  #  # (This is a robustness measure to prevent one pushkin stacking up with
-  #  #  queued requests and saturating the inbound connection queue of a load
-  #  #  balancer or reverse proxy).
-  #  # Defaults to 512 if unset.
+  #  # Authentication
   #  #
-  #  #inflight_request_limit: 512
-
-  # This is an example APNs push configuration using key authentication.
-  #
-  #com.example.myapp2.ios:
-  #  type: apns
+  #  # Two methods of authentication to APNs are currently supported.
+  #  #
+  #  # You can authenticate using a key:
   #  keyfile: my_key.p8
   #  key_id: MY_KEY_ID
   #  team_id: MY_TEAM_ID
   #  topic: MY_TOPIC
   #
+  #  # Or, a certificate can be used instead:
+  #  certfile: com.example.myApp_prod_APNS.pem
+  #
   #  # This is the maximum number of in-flight requests *for this pushkin*
   #  # before additional notifications will be failed.
   #  # (This is a robustness measure to prevent one pushkin stacking up with
@@ -231,12 +225,23 @@ apps:
   #  # Defaults to 512 if unset.
   #  #
   #  #inflight_request_limit: 512
+  #
+  #  # Specifies whether to use the production or sandbox APNs server. Note that
+  #  # sandbox tokens should only be used with the sandbox server and vice versa. 
+  #  #
+  #  # Valid options are:
+  #  #   * production
+  #  #   * sandbox
+  #  #
+  #  # The default is 'production'. Uncomment to use the sandbox instance.
+  #  #platform: sandbox
 
   # This is an example GCM/FCM push configuration.
   #
   #com.example.myapp.android:
   #  type: gcm
   #  api_key: your_api_key_for_gcm
+  #
   #  # This is the maximum number of connections to GCM servers at any one time
   #  # the default is 20.
   #  #max_connections: 20