Socket Servers¶

Asynchronous application for serving requests on sockets. This is the base class of WSGIServer. All is needed by a SocketServer application is a callable which build a ProtocolConsumer for each new client request received. This is an example of a script for an Echo server:

import pulsar
from pulsar.apps.socket import SocketServer

class EchoServerProtocol(pulsar.ProtocolConsumer):
    ...

if __name__ == '__main__':
    SocketServer(EchoServerProtocol).start()

Check the echo server example for detailed implementation of the EchoServerProtocol class.

Socket Server Settings¶

All standard application settings can be applied to a SocketServer. In addition, the following are specific to sockets and can be used to fine tune your application:

bind¶

To specify the address to bind the server to:

python script.py --bind 127.0.0.1:8070

This will accept connection from the 127.0.0.1 network interface and port 8070. This means pulsar will be able to accept connections only from clients running into the same computer it is running.

On the other hand, it is possible to listen for connections from all the network interfaces available on the server by specifying :<port>. For example, this will listen for both ipv4 and ipv6 sockets on all hosts on port 8080:

python script.py --bind :8080

Use this notation when running pulsar inside Docker or any other container.

You can bind to a random available port by specifying 0 as the port number:

python script.py --bind :0

useful during testing.

backlog¶

To specify the maximum number of queued connections you can use the backlog settings. For example:

python script.py --backlog 1000

rarely used.

keep_alive¶

To control how long a server Connection is kept alive after the last read from the remote client, one can use the keep-alive setting:

python script.py --keep-alive 10

will close client connections which have been idle for 10 seconds.

TLS/SSL support¶

Transport Layer Security (often known as Secure Sockets Layer) is handled by the cert-file and key-file settings:

python script.py --cert-file server.crt --key-file server.key

Concurrency¶

When running a SocketServer in multi-process mode (default), the application, create a listening socket in the parent (Arbiter) process and then spawn several process-based actors which listen on the same shared socket. This is how pre-forking servers operate.

When running a SocketServer in threading mode:

python script.py --concurrency thread

the number of Actor serving the application is set to 0 so that the application is actually served by the arbiter event-loop (we refer this to a single process server). This configuration is used when debugging, testing, benchmarking or on small load servers.

In addition, a SocketServer in multi-process mode is only available for:

Posix systems.
Windows running python 3.2 or above (python 2 on windows does not support the creation of sockets from file descriptors).

Check the SocketServer.monitor_start() method for implementation details.

API¶

Socket Server¶

class pulsar.apps.socket.SocketServer(callable=None, load_config=True, **params)[source]¶

A Application which serve application on a socket.

It bind a socket to a given address and listen for requests. The request handler is constructed from the callable passed during initialisation.

address¶: The socket address, available once the application has started.

create_server(worker)[source]¶

Create the Server which will listen for requests.

Returns:	a `TcpServer`.

monitor_start(monitor)[source]¶

Create the socket listening to the bind address.

If the platform does not support multiprocessing sockets set the number of workers to 0.

protocol_factory()[source]¶

Factory of ProtocolConsumer used by the server.

By default it returns the Application.callable().

server_factory(*args, **kw)[source]¶: Create a TcpServer.

worker_start(worker, exc=None)[source]¶: Start the worker by invoking the create_server() method.

UDP Socket Server¶

class pulsar.apps.socket.UdpSocketServer(callable=None, load_config=True, **params)[source]¶

A SocketServer which serves application on a UDP sockets.

It binds a socket to a given address and listen for requests. The request handler is constructed from the callable passed during initialisation.

address¶: The socket address, available once the application has started.

create_server(worker)[source]¶

Create the Server which will listen for requests.

Returns:	the server obtained from `server_factory()`.

monitor_start(monitor)[source]¶

Create the socket listening to the bind address.

If the platform does not support multiprocessing sockets set the number of workers to 0.

protocol_factory()[source]¶: Return the DatagramProtocol factory.

server_factory(*args, **kw)[source]¶: By default returns a new DatagramServer.