Callback usability (#40)

Callback example: Expect full cert chain and print the server's URL for convenience
AbstractCallback: Allow changing route

Previously some users would try to provide only the certificate without
the chain, leading to confusion.

README.rst

@@ -69,6 +69,14 @@ the Threema gateway. Run the following command to see usage information:
 
     $ threema-gateway --help
 
+Examples
+********
+
+You can find a few example scripts in the ``examples/`` directory.
+
+Note that most of them need to be adjusted to at least add your gateway ID
+credentials before they run successfully.
+
 Feature Levels
 **************
 

examples/callback.py

@@ -1,4 +1,5 @@
 import asyncio
+import ipaddress
 
 import logbook
 import logbook.more
@@ -26,11 +27,12 @@ def start():
     )
 
     # Create the callback instance
-    callback = Callback(connection)
+    route = '/gateway_callback'
+    callback = Callback(connection, route=route)
 
     # Start the callback server and listen on any interface at port 8443
     server = yield from callback.create_server(
-        certfile='PATH_TO_SSL_PEM_CERTIFICATE',
+        certfile='PATH_TO_SSL_PEM_CERTIFICATE_CHAIN',
         keyfile='PATH_TO_SSL_PRIVATE_KEY',
         port=8443
     )
@@ -55,6 +57,14 @@ def stop(server, callback):
         server, callback = loop.run_until_complete(start())
         # Ctrl+C: Terminate the server and the callback application
         try:
+            print('Listening on:\n')
+            for socket in server.sockets:
+                host, port, *_ = socket.getsockname()
+                host = ipaddress.ip_address(host)
+                if isinstance(host, ipaddress.IPv6Address):
+                    host = '[{}]'.format(host)
+                print('  https://{}:{}{}'.format(host, port, callback.route))
+            print('\nStarted callback server. Press Ctrl+C to terminate.')
             loop.run_forever()
         except KeyboardInterrupt:
             pass

threema/gateway/e2e.py

@@ -142,13 +142,13 @@ class AbstractCallback(metaclass=abc.ABCMeta):
     Raises :exc:`TypeError` in case no valid certificate has been
     provided.
     """
-    def __init__(self, connection, loop=None):
+    def __init__(self, connection, loop=None, route='/gateway_callback'):
         self.connection = connection
         # Note: I'm guessing here the secret must be ASCII
         self.encoded_secret = connection.secret.encode('ascii')
         self.loop = asyncio.get_event_loop() if loop is None else loop
         # Create router
-        self.router = self.create_router()
+        self.router = self.create_router(route)
         # Create application
         self.application = self.create_application(self.router, loop)
         self.handler = self.create_handler()
@@ -160,9 +160,10 @@ def create_ssl_context(self, certfile, keyfile=None):
         ssl_context.load_cert_chain(certfile=certfile, keyfile=keyfile)
         return ssl_context
 
-    def create_router(self):
+    def create_router(self, route):
+        self.route = route
         router = UrlDispatcher()
-        router.add_route('POST', '/gateway_callback', self._handle_and_catch_error)
+        router.add_route('POST', route, self._handle_and_catch_error)
         return router
 
     # noinspection PyMethodMayBeStatic