What to change for production
The project works and every page of it was run. This page is the one every project needs and few write: what the measurements say the next version should do differently, and what should be left exactly as it is. Nothing here is a number that was not measured on the pages before it.
What the project measured
| Measurement | Value | Page |
|---|---|---|
| the core prices one order | two multiplications, a few moves | core |
| a subprocess per call | 4.431 ms median, five rounds | ctypes |
| a ctypes call into the module | 2.127 microseconds median | ctypes |
| the service under a timeout | 504 one second after the request | errors |
| the Python tests | six tests in 0.185 s | tests |
Two of those numbers decide the next version. The core is cheap; starting a process is what costs 4.3 milliseconds. And the difference between the two ways in is a factor of about two thousand, which is large enough that a batch of orders should never pay it per order.
Batch the calls before anything else
The core already reads a stream: the run on its page is five requests in one process and five answers out. The service throws that away by starting a process per HTTP request, which is right for one order at a time and wrong for a client that prices a thousand. The first production change is a batch endpoint that takes N fixed records, runs one core for all of them and returns N answers: the same protocol, one process, and the cost per order falls from 4.3 milliseconds to something close to the unit\'s own work.
The second change is a pool of long-lived cores, which is the same idea for single orders: a core that reads a request, writes an answer and waits for the next one, with a supervisor that restarts it if it dies. That is more moving parts than a fork, and it is the point at which the ctypes path becomes the simpler option for a single-process service: 2 microseconds and no supervisor, at the price of a crash that takes the service with it.
Version the contract
The thirty-byte request has no version field, and that is the one design mistake worth fixing while the interface is young. The first byte of the answer is the status; the first byte of the request is the first letter of an order id. A production request should start with a version and the answer should echo it, exactly as the capstone C interface does: a core that receives version 2 refuses it with a status instead of reading the bytes as if the layout had not changed. The cost is one byte and one check; the cost of adding it later is every client in the field.
The JSON side needs the same discipline for the same reason. The document has field names that are now a public interface; a rename is a breaking change and should be a version, not a patch.
Operations
The service has the four things an operator asks for first, and they are worth listing because a wrapper often lacks them: a health endpoint that reports the core and not only the socket, a timeout on the child, a status line per request, and a status code that distinguishes a client error from a server one. What it still needs:
- A body size limit. The service reads Content-Length and trusts it; a production version caps it at a few kilobytes and answers 413 above.
- A request id in the log and in the answer. The order id is a start, but a request that fails before the core runs has none.
- A test for each environment failure. The three cases of the error page that start their own server are not in the suite, and they are the ones a deployment gets wrong.
- A non-root user in the image and pinned versions. The Dockerfile on the deployment page uses alpine:3.24 and installs two packages; a production image pins the base by digest and the packages by version.
What not to change
The temptation in a project like this is to move the logic into the modern layer and leave COBOL as a thin file reader. The pages here argue against it. The validation rules and the pricing are the part of the system that has been tested for years, the COBOL test driver covers them in five cases that run in milliseconds, and the integer cents on the wire are exact in both languages because the arithmetic is integer in both. Moving that code to Python would buy nothing that the 4.3 milliseconds costs, and it would put the money arithmetic on the wrong side of the decimal comparison.
What should change is everything around it: the batching, the version field, the limits, the tests of the failures, the container. That is the modernisation this group demonstrates, and it is the one that keeps the working program working.
A closing word
A COBOL core behind a modern layer is not a compromise or a temporary bridge. It is a service with an unusual property: the part that computes money is the part that has been in production the longest, and the part that changes most often is the part written in the language the new team knows. The interface between them is thirty bytes and a status field, it fits on a page, and every program on these pages was built and run to prove it.
The course lessons behind the project are SELECT and FD, CALL and USING and Calling COBOL from Python; the comparison pages are in COBOL and C++ side by side, and the test material in Testing COBOL code.
Every number on this page comes from a run in this container: cobc (GnuCOBOL) 3.2.0 and Python 3.14.10 on Alpine Linux 3.24.3 (x86_64) with nproc 4. The Dockerfile of the deployment page was built on the host in Docker, run with a published port and called from the host.
Article author: Arthur Isaev