ZMQ Async Command Runner

📚 Table of Contents

• About
• Features
• Requirements
• How to Run
• Interview Notes
• License

---

📝 About

This project is an interview task to demonstrate backend proficiency with asynchronous programming and message routing using ZeroMQ and Python.

The goal is to build a command runner server where clients can send shell commands, and workers execute them concurrently without blocking the system.

---

🚀 Features

• Asynchronous server with asyncio and zmq.asyncio
• ROUTER/DEALER (brokered) pattern for concurrency
• Subprocess command execution with structured JSON input/output
• Validation with pydantic
• Clean command-line client interface
• Timeout on commands

---

📦 Requirements

• Python 3.11+
• ZeroMQ
• Rich (for client output)
• aiofile
• pydantic

Install dependencies:

uv pip install .

🛠️ How to Run

1. Start the Server

git clone https://github.com/TorhamDev/command-over-zmq.git && cd command-over-zmq

python worker/main.py

This starts:

• A ROUTER/DEALER-based broker (with ZMQ request-reply behind it)

• At least one asynchronous worker that executes shell commands

2. Run the Client

Prepare a JSON file like this:

{
  "command_type": "os",
  "command_name": "echo",
  "parameters": ["Hello, world!"]
}

Or multiple:

[
  {
    "command_type": "shell",
    "command_name": "echo",
    "parameters": ["Hello, world!"]
  },
  {
    "command_type": "shell",
    "command_name": "sleep",
    "parameters": ["2"]
  }
]

Then run:

# -f is json file path and -a is server address
python client.py -f commands.json -a tcp://localhost:5555

use client.py --help to see help.

via Docker

build with:

docker build -t worker .

run your Docker container

docker run -p 5554:5554 worker

🙋 Interview Notes

This code was written as part of a timed technical interview task with limited scope. While functional and modular, it can be expanded with:

1- Job queuing & status tracking

2- Output streaming

3- Web UI or REST API interface

4- Testing using pytest

License

This project is licensed under the GNU General Public License v3.0 License - see the LICENSE file for details.