A Python service in front of the Haskell core

A command line program is not a service. Something has to listen on a socket, turn an HTTP request into a line, start the program, read the answer and turn it back into JSON, and that something is usually the language the rest of the product is written in. Here it is Python: the standard library has an HTTP server and a subprocess module, so the whole layer is two short files.

The design is deliberately the simplest one that works. There is one process per request, which costs a few milliseconds and is measured on the timing page; it needs no supervision, no protocol state and no restart logic, and it cannot leak a child process. The alternative, one long-lived child with two pipes, is faster and is the note at the end of the page.

A service in front of a program

The layer has three jobs. It maps a URL and a method to a request line, it maps the answer line to an HTTP status and a JSON object, and it never lets a failure of the child take the server down. Everything else, the pricing, the codes and the formatting, stays in the Haskell core.

The split is what makes the core testable on its own and the service testable without a socket, which the test page does in two layers: handle_line is called directly with a fake runner, and the real server is started in a thread and called over HTTP.

The Python side of the protocol

run_core starts the executable, writes one line, reads the answer and checks that it got one. handle_line is a pure function of the answer: the match statement splits it into the status and the payload, and an answer in neither shape becomes a 502 rather than a crash, because a core that answers something unexpected is a broken deployment.

"""The Python side of the line protocol: one request line, one answer line.""" import os import subprocess CORE = os.environ.get("CORE_BIN", "./core") def run_core(line: str) -> str: """Run the Haskell executable for one line and return its answer.""" result = subprocess.run( [CORE], input=line + "\n", capture_output=True, text=True, timeout=5, check=True, ) answer = result.stdout.strip() if not answer: raise RuntimeError(f"the core answered nothing for {line!r}") return answer def handle_line(line: str, runner=run_core) -> tuple[int, dict]: """Turn one request line into an HTTP status and a JSON-able answer.""" answer = runner(line) match answer.split(): case ["OK", cents, money]: return 200, {"line": answer, "total": int(cents), "money": money} case ["ERR", code, *message]: return 400, {"line": answer, "error": code, "message": " ".join(message)} case _: return 502, {"line": answer, "error": "E_CORE"}

Two details are worth keeping. The runner is a parameter with a default, so a test can pass a fake and the mapping can be tested without the executable. And CORE_BIN is read from the environment, so the service can be started next to a binary in another directory without an edit.

The HTTP handler

The handler is one method. A request to anything but /quote is a 404, the body is decoded and stripped, and the answer is JSON with a status that comes from the core through handle_line. The except clause is the only place in the layer that catches broadly, and it exists for one reason: a missing binary or a timeout must be a 500 for this request, not an exception that ends the server.

"""An HTTP service in front of the Haskell core, one subprocess per request.""" import json import os import sys from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer from protocol import handle_line class Handler(BaseHTTPRequestHandler): """Answer POST /quote with the JSON form of one core answer.""" def do_POST(self) -> None: if self.path != "/quote": self.send_error(404, "unknown path") return length = int(self.headers.get("Content-Length") or 0) body = self.rfile.read(length).decode("utf-8").strip() try: status, payload = handle_line(body) except Exception as error: # the service answers 500, it does not die status, payload = 500, {"error": "E_CORE", "message": str(error)} data = json.dumps(payload).encode("utf-8") self.send_response(status) self.send_header("Content-Type", "application/json") self.send_header("Content-Length", str(len(data))) self.end_headers() self.wfile.write(data) def log_message(self, template: str, *args: object) -> None: sys.stderr.write("%s\n" % (template % args)) def main() -> None: port = int(sys.argv[1]) if len(sys.argv) > 1 else 8080 host = os.environ.get("BIND", "127.0.0.1") server = ThreadingHTTPServer((host, port), Handler) print(f"listening on http://{host}:{port}/quote", flush=True) server.serve_forever() if __name__ == "__main__": main()

ThreadingHTTPServer answers each request in its own thread, which matches the one-process-per-request design: two requests do not queue behind each other, and each one has a child of its own. The log_message override sends the log to standard error in one line per request, which is what a container collects. The bind address is the one exception to "127.0.0.1 everywhere": it is read from BIND because a server that listens on the loopback address inside a container answers nobody outside it, and the deployment page shows that failure and its fix.

Started and called here

The server is started in the background on port 8765 and called with curl, one request per line. The -w " %{http_code}" puts the status on the same line as the body, and the three answers are the three shapes of the protocol:

python3 service.py 8765 &

curl -s -w " %{http_code}\n" -X POST --data 'PRICE tea 3' http://127.0.0.1:8765/quote

{"line": "OK 750 7.50", "total": 750, "money": "7.50"} 200
{"line": "OK 2632 26.32", "total": 2632, "money": "26.32"} 200
{"line": "ERR E_SKU unknown sku: gold", "error": "E_SKU", "message": "unknown sku: gold"} 400

The status is the core's decision and not a convention of the layer: OK becomes 200, ERR becomes 400, and the JSON carries both the line and its parts so that a client can log one and use the other. The server wrote one line per request to its log:

listening on http://127.0.0.1:8765/quote
"POST /quote HTTP/1.1" 200 -
"POST /quote HTTP/1.1" 200 -
"POST /quote HTTP/1.1" 400 -
code 501, message Unsupported method ('GET')
"GET /quote HTTP/1.1" 501 -
code 404, message unknown path
"POST /other HTTP/1.1" 404 -

The two edges of the service

The first edge is a method the handler does not implement. A GET arrives, do_POST is not called, and the base class answers 501 with a page of HTML. That is honest and it is not what a JSON client expects, which is the argument for overriding do_GET to answer 405 with the same JSON shape.

GET /quote 501
POST /other 404

The second edge is a wrong path: 404 from the handler, with a plain-text message, and it never reaches the child. Both edges are the kind of thing a test suite should pin down, and the test page does pin down the happy path and the error path of /quote.

The long-lived child. One process per request pays the process start on every call, which the timing page measures in milliseconds. A service with a high request rate keeps one child alive, writes a line to its stdin and reads a line from its stdout, and the cost drops to the line protocol itself. The price is that the child has to be restarted when it dies, two threads cannot share it without a lock, and a timeout means killing and restarting it. That is the trade, and the next page removes the boundary instead of optimising it.

The service ran here with Python 3.14.10 and GHC 9.10.3 on Alpine Linux 3.24.3 (x86_64) in a Docker container, and the calls above were made with the curl of that image.

Article author: Arthur Isaev

Banner image