Skip to content
Stephenson-SoftwarePublic

About

A simple chat application created to practice socket programming.

Resources

Stars

0 stars

Watchers

1 watching

Forks

Latest commit

 

History

58 Commits

Folders and files

Repository files navigation

Curabitur

This repository is for practicing socket programming in Python by creating a simple chat application.

A real curabitur chat: the server in the left pane, the client in the right

A real chat on one machine: the server on the left, the client on the right. The client then closes with Ctrl-D and the server with Ctrl-C.

Naming

The name of this repository is derived from the Latin word "curabitur" which means "to chat".

How to Run

Locally

  1. Clone this repository
  2. Run python3 server/src/chatServer.py in one terminal
  3. Note the IP address the server prints on its Listening on <IP>:36578... line
  4. Run CHAT_SERVER_IP=<IP> python3 client/src/chatClient.py in another terminal, using the address from the previous step

Docker

  1. Clone this repository
  2. Open a terminal and navigate to the root of the repository
  3. Run bash run_server.sh in that terminal
  4. Note the IP address the server prints on its Listening on <IP>:36578... line
  5. Open another terminal and navigate to the root of the repository
  6. Run bash run_client.sh <IP> in the second terminal, using the address from step 4

Taking Turns

The client speaks first, then the two programs take turns: each sends one message and waits for the other to answer. Pressing Enter on an empty line sends nothing and shows the prompt again, since the other side would otherwise wait for a message that never arrives.

Keep each message to 1024 bytes or fewer (1024 plain ASCII characters; fewer when the message has accented letters or emoji, which take more than one byte each). Each program reads a turn with a single 1024-byte read, so a longer message arrives in pieces that the other side treats as separate turns. The turns then fall out of step, and replies show up one turn late or joined together.

Messages are UTF-8. Received bytes that are not valid UTF-8 are shown as the replacement character �, and the chat carries on. A typed line that is not valid text is not sent: the program reports That line is not valid text. Type it again. and shows the prompt again.

Ending a Session

Press Ctrl-D at either program's prompt to close its input. Both the server and the client report Input closed. Exiting. and shut down cleanly.

Pressing Ctrl-C works at any point — at a prompt, while the server is waiting for a client, or while the client is retrying a connection. The program reports Interrupted. Exiting. and shuts down cleanly.

If the server goes away while the client is connected, the client reports Server disconnected. Exiting. and shuts down cleanly rather than prompting for input on a closed connection. A client waiting for a reply reports this straight away; a client at its prompt reports it after the next message is typed. When the client goes away, even abruptly, the server returns to waiting for a new connection. A server at its prompt notices this only after the next reply is typed, and it then prints its Listening on <IP>:36578... line again.

The server chats with one client at a time. A second client that connects during a chat is not accepted, although it looks connected: it shows its prompt and takes a message, which the server never shows. When the first chat ends, the second client is disconnected and reports Server disconnected. Exiting. as described above, and the server waits for a new connection.

If CHAT_SERVER_IP is not set or is empty, the client reports CHAT_SERVER_IP environment variable not set. Exiting. and exits with status 1. If it holds an address that cannot be resolved, such as a mistyped IP or an unknown host name, the client reports Could not resolve CHAT_SERVER_IP '<value>': <reason>. Exiting. and exits with status 1 rather than retrying. Likewise, if the server's host or network cannot be reached ("No route to host", "Network is unreachable"), the client reports Connection to <IP>:36578 failed: <reason>. Exiting. and exits with status 1. A server that refuses the connection, or does not answer before the connection times out, is retried with a one-second pause between attempts until it is reachable.

The server listens on the IPv4 address its machine's host name resolves to. If the host name cannot be resolved, for example because it has no entry in /etc/hosts or DNS, the server reports Could not resolve this machine's host name '<name>': <reason>. Exiting. and exits with status 1.

If the server cannot listen on its port, most often because another server is already running on it, it reports Server on <IP>:36578 failed: <reason>. Exiting. (for example Address already in use) and exits with status 1.

A connection that fails mid-chat in some way other than a reset, a broken pipe or a close, such as Connection timed out, makes the program that sees the failure exit with status 1. The server reports Server on <IP>:36578 failed: <reason>. Exiting. and does not wait for a new connection. The client reports Connection to <IP>:36578 failed: <reason>. Exiting. in the same case.

Usage reporting

Usage reporting is on by default: the server and the client each send the program's name (curabitur), its version and the events startup (when the program starts) and connected (when the server accepts a client, or the client reaches a server) to trace at https://trace.danielstephenson.dev. Every event carries a role tag saying which of the two sent it (server or client), and a random installation ID (the tag install) so installations can be counted rather than events. Nothing about you, your machine, your IP address, the addresses you connect to or the messages is sent. The report is made from a background thread, never blocks the chat, and is dropped silently if the service is unreachable.

The first launch of each program writes a settings.json next to its src/ directory (server/settings.json, client/settings.json) and prints a one-line notice. If that file exists but cannot be read, for example because it is not valid JSON, the program reports Could not read <path> (<reason>); usage reporting is off until it is fixed., leaves the file alone and carries on without reporting. A file that is valid JSON but not an object, such as [], is treated the same way. If the file cannot be written, for example because the directory is read-only, the program reports Could not write <path> (<reason>); the notice above will be shown again next time. and carries on as if the default block, with "enabled": true, had been written.

The installation ID is a random UUID kept in a file named trace-install-id in the user data directory, shared by the server and the client on the same machine: ~/.local/share/curabitur/ on Linux (or $XDG_DATA_HOME/curabitur/), ~/Library/Application Support/curabitur/ on macOS and %APPDATA%\curabitur\ on Windows. It identifies no person, account or address; delete the file to get a new one. Setting the environment variable TRACE_INSTALL_ID sends that value instead, without surrounding whitespace, and leaves the file alone. An empty or whitespace-only value is ignored and the file is used. A value longer than 255 characters turns usage reporting off, with no message. The file is only created while reporting is on, so every opt-out below also stops it.

To turn reporting off, any one of these is enough:

  • "usage_reporting": {"enabled": false} in that program's settings.json:

    {
      "usage_reporting": {
        "enabled": false
      }
    }

    enabled fails closed: only true (or the string "true", "on", "yes" or "1") keeps reporting on, so a quoted "false", "off", null or a typo turns it off; a block with no enabled entry keeps the default (on). A usage_reporting entry that is not an object, such as "usage_reporting": false, is read the same way and turns reporting off. An existing usage_reporting entry is never rewritten, so an opt-out stays put. Other spellings count as off too: a block written as "usage-reporting", "usageReporting" or "UsageReporting" (or any spelling of "usage reporting") holding false or "enabled": false, and inside the block "enable": false, "Enabled": false or "disabled": true; the real usage_reporting block is then written with "enabled": false next to it rather than with reporting on.

  • the environment variable TRACE_USAGE_REPORTING=off, which turns off every program that reports to trace; any value but blank, true, on, yes or 1 does (false, 0, no, a typo, ...; case does not matter)

  • the environment variable DO_NOT_TRACK=1 (see consoledonottrack.com); any value but blank, 0, false, off or no does (case does not matter)

Any other value, including an empty one, leaves the settings.json setting in charge.

The environment variables win over settings.json. Under Docker the containers are removed on exit, so a settings.json written inside one does not persist; run_server.sh and run_client.sh pass TRACE_USAGE_REPORTING, DO_NOT_TRACK and TRACE_INSTALL_ID through to the container, so TRACE_USAGE_REPORTING=off bash run_server.sh turns reporting off there. A settings.json that is already in server/ or client/ when the image is built, for example from an earlier local run, is copied into the image along with the rest of the directory, and every container started from that image reads it. An opt-out made there therefore applies under Docker too, from the next build on; run_server.sh and run_client.sh rebuild the image every time they run. For the same reason as the settings.json written inside a container, a container's installation ID file does not persist either: each run gets a new ID unless TRACE_INSTALL_ID is set. The endpoint and key entries in the settings block select where reports go and the key they are sent with. Each program carries its own copy of the client (src/trace_client.py, vendored from trace-client-python) and of the settings handling (src/usage_reporting.py), because each is built into its own image from its own directory.

Details: https://danielstephenson.dev/usage-reporting

Tests

python3 -m unittest discover -s tests

The suite covers the server's and the client's chat loops against mocked sockets and input (binding and retrying, sending and printing messages, exiting on an address or host name that cannot be resolved, a host that cannot be reached or a port that is already in use, and exiting or listening again on closed input, Ctrl-C or a lost connection), the usage-reporting settings, notice, opt-outs and events for both programs against a loopback stub (it never contacts the real service), the vendored client, and that the client's and the server's copies have not drifted apart.

Learning Resources

How the screenshot was captured

docs/images/curabitur-chat.gif was recorded on 2026-10-18 from real runs of python3 server/src/chatServer.py and python3 client/src/chatClient.py (Python 3.12), side by side in two tmux panes, with TRACE_USAGE_REPORTING=off set so that no usage reports were sent. The messages were typed into the panes by a script, and the recorded terminal output was rendered to an image with pyte and Pillow. Nothing in the output was edited; only the window frame was added.

License

This project is licensed under the Stephenson Software Non-Commercial License (Stephenson-NC). See LICENSE for the terms, which permit non-commercial use only. The full license text is published at https://github.com/Stephenson-Software/stephenson-nc-license.

About

A simple chat application created to practice socket programming.

Resources

Stars

0 stars

Watchers

1 watching

Forks

Contributors

Languages