An Echo Client/Server Over TCP

To see how to create a server and a client with the minimum requirements, let’s create a server that will return everything sent by a connected client.

Note

This page uses two different API variants:

• Synchronous API with classic def functions, usable in any context.

• Asynchronous API with async def functions, using an asynchronous framework to perform I/O operations.

All asynchronous API examples assume that you are using either asyncio or trio, but you can use a different library thanks to the asynchronous backend engine API.

---

The Communication Protocol

Before doing all this networking stuff, you need to know what you want to transmit and in what format. It is your communication protocol.

Choose The Serializer

There is a bunch of serializers available in easynetwork.serializers for everyone to enjoy:

• JSONSerializer: an incremental serializer using the json module.

• PickleSerializer: a one-shot serializer using the pickle module.

• StringLineSerializer: an incremental serializer for communication based on ASCII character strings (e.g. FTP).

• etc.

For the tutorial, JSONSerializer will be used.

Build Your Protocol Object

For communication via TCP, a StreamProtocol protocol object must be created.

json_protocol.py

from __future__ import annotations

from typing import Any, TypeAlias

from easynetwork.protocol import StreamProtocol
from easynetwork.serializers import JSONSerializer

# Use of type aliases in order not to see two Any types without real meaning
# In our case, any serializable object will be sent/received
SentDataType: TypeAlias = Any
ReceivedDataType: TypeAlias = Any


class JSONProtocol(StreamProtocol[SentDataType, ReceivedDataType]):
    def __init__(self) -> None:
        super().__init__(JSONSerializer())

Note

Of course, you are under no obligation to write a subclass. But see this note for details.

The Server

Now that we have established the communication protocol, we can create our server.

Create Your Request Handler

First, you must create a request handler class by subclassing the AsyncStreamRequestHandler class and overriding its handle() method; this method will process incoming requests.

echo_request_handler.py

from __future__ import annotations

from collections.abc import AsyncGenerator
from typing import Any, TypeAlias

from easynetwork.exceptions import StreamProtocolParseError
from easynetwork.servers.handlers import AsyncStreamClient, AsyncStreamRequestHandler, INETClientAttribute

# These TypeAliases are there to help you understand
# where requests and responses are used
RequestType: TypeAlias = Any
ResponseType: TypeAlias = Any


class EchoRequestHandler(AsyncStreamRequestHandler[RequestType, ResponseType]):
    async def handle(
        self,
        client: AsyncStreamClient[ResponseType],
    ) -> AsyncGenerator[None, RequestType]:
        try:
            request: RequestType = yield  # A JSON request has been sent by this client
        except StreamProtocolParseError:
            # Invalid JSON data sent
            # This is an example of how you can answer to an invalid request
            await client.send_packet({"error": "Invalid JSON", "code": "parse_error"})
            return

        client_address = client.extra(INETClientAttribute.remote_address)
        print(f"{client_address.host} sent {request}")

        # As a good echo handler, the request is sent back to the client
        response: ResponseType = request
        await client.send_packet(response)

Note

Pay attention to handle(), it is an asynchronous generator function. All requests sent by the client are literally injected into the generator via the yield statement.

async def handle(
    self,
    client: AsyncStreamClient[ResponseType],
) -> AsyncGenerator[None, RequestType]:
    try:
        request: RequestType = yield  # A JSON request has been sent by this client
    except StreamProtocolParseError:
        # Invalid JSON data sent
        # This is an example of how you can answer to an invalid request
        await client.send_packet({"error": "Invalid JSON", "code": "parse_error"})
        return

You can yield several times if you want to wait for a new packet from the client in the same context.

Warning

Leaving the generator will not close the connection, a new generator will be created afterwards. You may, however, explicitly close the connection if you want to:

await client.aclose()

Start The Server

Second, you must instantiate the TCP server class, passing it the server’s address, the protocol object instance, and the request handler instance.

SynchronousAsynchronous (asyncio)Asynchronous (trio)

server.py

from __future__ import annotations

from easynetwork.servers import StandaloneTCPNetworkServer

from echo_request_handler import EchoRequestHandler
from json_protocol import JSONProtocol


def main() -> None:
    host = None
    port = 9000
    protocol = JSONProtocol()
    handler = EchoRequestHandler()

    with StandaloneTCPNetworkServer(host, port, protocol, handler) as server:
        server.serve_forever()


if __name__ == "__main__":
    try:
        main()
    except* KeyboardInterrupt:
        pass

Note

Setting host to None will bind the server to all interfaces. This means the server is ready to accept connections with IPv4 and IPv6 addresses (if available).

The Client

This is the client side:

SynchronousAsynchronous (asyncio)Asynchronous (trio)

client.py

from __future__ import annotations

import sys

from easynetwork.clients import TCPNetworkClient

from json_protocol import JSONProtocol


def main() -> None:
    host = "localhost"
    port = 9000

    # Connect to server
    with TCPNetworkClient((host, port), JSONProtocol()) as client:
        # Send data
        request = {"command-line arguments": sys.argv[1:]}
        client.send_packet(request)

        # Receive data from the server and shut down
        response = client.recv_packet()

    print(f"Sent:     {request}")
    print(f"Received: {response}")


if __name__ == "__main__":
    main()

Outputs

The output of the example should look something like this:

Server:

IPv4 connectionIPv6 connection

(.venv) $ python server.py
127.0.0.1 sent {'command-line arguments': ['Hello', 'world!']}
127.0.0.1 sent {'command-line arguments': ['Python', 'is', 'nice']}

Client:

(.venv) $ python client.py Hello world!
Sent:     {'command-line arguments': ['Hello', 'world!']}
Received: {'command-line arguments': ['Hello', 'world!']}
(.venv) $ python client.py Python is nice
Sent:     {'command-line arguments': ['Python', 'is', 'nice']}
Received: {'command-line arguments': ['Python', 'is', 'nice']}