Application usage¶
This module provide Application
class, which used as entry point
for your REST applications with WebSockets.
Run a instance of application¶
Before running the server with you application necessary to satisfy few conditions:
1. Import required modules of aiorest-ws
package to write your own
handler. It can be method-based:
from aiorest_ws.views import MethodBasedView
class HelloWorld(MethodBasedView):
def get(self, request, *args, **kwargs):
return "Hello, world!"
or function-based view:
from aiorest_ws.decorators import endpoint
@endpoint(path='/hello', methods='GET')
def hello_world(request, *args, **kwargs):
return "Hello, world!"
2. Add implemented endpoint to the instance of SimpleRouter
class or
derived from it. For method-based view its looks like this:
from aiorest_ws.routers import SimpleRouter
router = SimpleRouter()
router.register('/hello', HelloWorld, 'GET')
and a little bit different for a function-based approach:
from aiorest_ws.routers import SimpleRouter
router = SimpleRouter()
router.register_endpoint(hello_world)
3. Set user-defined router and start Application
instance via run
method:
# By default server listen on 127.0.0.1:8080
app = Application()
app.run(router=router)
Constructor arguments¶
Application instance can get in the constructor the next arguments:
- factory
- Factory class, used for instantiating protocol objects. Must be inherited
from the
RequestHandlerFactory
class. Default toRequestHandlerFactory
class
- protocol
- Protocol class, used for processing client requests. Must be inherited from
the
RequestHandlerProtocol
class. Default toRequestHandlerProtocol
class
- certificate
- Path to SSL certificate. Default to
None
- key
- Path to private key of SSL certificate. Default to
None
- middlewares
- List of middlewares, applied for every request. Default to
[]
Middlewares¶
Application
can receive list of middlewares, which used for
pre-processing requests in the order of their appearance.
Example of using:
default_middlewares = (MyCustomMiddleware, )
app = Application(middlewares=default_middlewares)
app.run()
For more demonstrative example you can look onto example of API with JSON WebTokens
Run method¶
Note
If you want to change behaviour of run
method, then focus on override
some inner function or procedure. For example, it can be generate_factory
method, which return configured factory class.
Run
method its a entry point for your all applications, because it start
server on the specified ip and port. Default realization of this method can get
the next parameters:
- ip
The hostname to listen on. Default to
'127.0.0.1'
- port
The port of the webserver. Defaults to
8080
- path
Path to REST APIs relatively to server. Default to
''
For example if user has left
ip
,port
by default, and setpath='api'
, then server REST with WebSockets will be available on thews://127.0.0.1:8080/api
orwss://127.0.0.1:8080/api
(when SSL enabled)
- log_level
If specified, set logging level. Default to
'info'
. Available options are:'info'
,'debug'
,'critical'
,'error'
,'warn'
,'trace'
- router
Router with registered endpoints Default to
None
(instead None objectApplication
using instance ofSimpleRouter
class)
- compress
Enable compressing for transmitted traffic. Default to
False
- accept_function
Function for compressing of transmitted traffic. Default function is
aiorest_ws.utils.websocket.deflate_offer_accept
. Using only whencompress
argument specified withTrue
value.
Running with SSL¶
Warning
Don’t use non-encrypted channels for transferring user data (passwords, tokens, etc.).
Aiorest-ws framework support running server with SSL. Just append certificate
and key
options to the Application
constructor:
# REST with WebSockets will be available on wss://127.0.0.1:8080
app = Application(certificate='path/to/my.crt', key='path/to/my.key')
app.run(host='127.0.0.1', port=8080, router=router)
In situations, when required to test your application for a work with SSL, but certificate has expired or have not provided by the customer, you can generate your own self-signed certificate via OpenSSL:
$ openssl genrsa -out server.key 2048
$ openssl req -new -key server.key -out server.csr
$ openssl x509 -req -days 3650 -in server.csr -signkey server.key -out server.crt
$ openssl x509 -in server.crt -out server.pem
Running with traffic compression¶
Application
instance have support to compress all transmitted
traffic by the network. This feature was taken from Autobahn.ws implementation
(which rely onto this document).
For enable this feature is enough to append compress
parameter with
True
value to the run
method:
app = Application()
app.run(compress=True)
By default using deflate compression method which is provided by “permessage-deflate” extension. If you
want to change this behaviour to a custom, then specify accept_function
argument with certain
functionality (as a function). For instance you can look on the
example
of autobahn-python repository.