freetser 0.1.0__tar.gz

freetser-0.1.0/PKG-INFO

@@ -0,0 +1,113 @@
+Metadata-Version: 2.3
+Name: freetser
+Version: 0.1.0
+Summary: A free-threaded HTTP server built on top of h11
+Author: Tip ten Brink
+Author-email: Tip ten Brink <tip@tenbrinkmeijs.com>
+Requires-Dist: h11>=0.16.0,<0.17.0
+Requires-Python: >=3.14
+Description-Content-Type: text/markdown
+
+# freetser
+
+**freetser** is a **free**-**t**hreaded HTTP/1.1 **ser**ver, i.e. it relies on a free-threaded build of Python where the GIL is disabled. Furthermore, it provides a built-in KV storage layer (which uses SQLite under the hood). It has only a single dependency outside the standard library, the wonderful pure Python sans IO-style HTTP/1.1 library known as [h11](https://github.com/python-hyper/h11).
+
+It aims to be a very simple synchronous web server that should work for a lot of projects that do not require multiple thousands of requests per second, although with a lot of cores and threads it can actually achieve about 10,000 requests per second on an untuned Linux system.
+
+## Architecture
+
+- Thread-per-connection (no thread pool), **no async**
+- Uses a pure Python HTTP/1.1 library (h11)
+- `socket` from the standard library for the actual TCP reading/writing
+- Single SQLite database thread (using `sqlite3` from the standard library), other threads simply send Python functions through a queue for it to execute
+
+## Quick start
+
+Ensure you are using a **free-threaded** build of Python, see [documentation here](https://docs.python.org/3/howto/free-threading-python.html). If using [`uv`](https://github.com/astral-sh/uv), which I highly recommend, you could use `uv python pin 3.14t` (where the `t` stands for the free-threaded version).
+
+Then, install `freetser` from PyPI with `uv add freetser`. 
+
+Finally, create a Python script (e.g. `main.py`) with the following code:
+
+```python
+import logging
+
+from freetser import (
+    Request,
+    Response,
+    ServerConfig,
+    Storage,
+    setup_logging,
+    start_server,
+)
+from freetser.server import StorageQueue
+
+logger = logging.getLogger("freetser.handler")
+
+def handler(req: Request, store_queue: StorageQueue | None) -> Response:
+    if req.path == "/":
+        return Response.text("Hello world!")
+
+    return Response.text("Not found!", status_code=404)
+
+
+def main():
+    listener = setup_logging()
+    listener.start()
+
+    config = ServerConfig(port=8000)
+    try:
+        start_server(config, handler)
+    except KeyboardInterrupt:
+        print("\nShutting down...")
+    finally:
+        listener.stop()
+
+
+if __name__ == "__main__":
+    main()
+```
+
+Then if you do `uv run main.py`, it will start the server on the default port of 8000.
+
+## Using the built-in storage
+
+`freetser` provides a built-in key-value (KV) store built on top of SQLite. It is not designed for speed, but for simplicity. First, define a database routine:
+
+```python
+def get_or_create(store: Storage) -> str:
+    key = "my_user_email"
+    result = store.get("USERS", key)
+    if result is None:
+        value = b"my.user@freetser.com"
+        store.add("USERS", key, value, 0)
+        return f"Created: {key}\n"
+    else:
+        value, counter = result
+        return f"Found: {key}, counter={counter}\n"
+```
+
+A database routine is simply a Python function or lambda that takes a `Storage` argument. Then, in your handler, call `result = store_queue.execute(get_or_create)`. The server will then execute this function on the database thread in a transaction, ensuring it either succeeds or fails. 
+
+This has some important consequences:
+- If any non-expected database error occurs (i.e. it does not derive from `StorageError`), the database thread will crash and the server will have to be restarted.
+- Therefore, you should **not** throw when you encounter application errors inside the routine, but instead return a value and handle the error in the handler. You can even just raise the error there, as when errors occur in the handler the server will simply return a 500 Internal Server Error but not crash (since the error is raised in the connection thread). 
+- Furthermore, try to only perform simple logic in the routines. Since we only have 1 database thread, all other threads have to wait on your routine to finish. So don't make any HTTP calls or other blocking requests. Put those in the handler instead. If this is a limitation, **don't use this library**. This library is explicitly not designed for highly concurrent use cases or high performance applications with hundreds of thousands of users. However, it should handle thousands just fine.
+
+For more examples, see `main.py` in the tests directory or check out the tests themselves.
+
+## Benchmarks
+
+In some basic stress testing on a local machine, we found that requests basically always take around 41-42 ms, giving a basic 25 requests per second. Note that we always perform at least a single SQLite operation, so every request has to go through the database thread.
+
+However, throughput can rise all the way to 5500 requests per second (using 300 request threads firing off requests on a keep-alive connection) without any real hit to latency, with requests still taking around 43 ms to complete on average (and at most 160 ms, hats off to the OS scheduler). From that point on, average request times start to climb as you add threads.
+
+Using 750 threads, throughput reaches 10,000 requests per second with an average request taking 53 ms. Using 1000 threads barely helps as throughput starts to level off rapidly, reaching 10,900 requests per second. 1200 threads wasn't possible to test without tuning OS settings.
+
+Benchmark machine specs: Intel Core Ultra 7 155H (22 vCPUs), Linux 6.17, 32GB LPDDR5x-7467 memory
+
+## Background
+
+I wanted to minimize dependencies and use the standard library's sqlite3 interface. However, sqlite3 is not made for async. Therefore, I wanted a synchronous web server. However, while there exists projects like Flask and Bottle, I simply could not grok how to easily integrate them with sqlite3. Furthermore, they are not designed to utilize Python's recent free-threaded build. 
+
+Most of all, I wanted a project where everyone can read the code and understand what it's doing, while also providing a built-in storage mechanism so you can use it for small-scale production use cases.

freetser-0.1.0/README.md

@@ -0,0 +1,103 @@
+# freetser
+
+**freetser** is a **free**-**t**hreaded HTTP/1.1 **ser**ver, i.e. it relies on a free-threaded build of Python where the GIL is disabled. Furthermore, it provides a built-in KV storage layer (which uses SQLite under the hood). It has only a single dependency outside the standard library, the wonderful pure Python sans IO-style HTTP/1.1 library known as [h11](https://github.com/python-hyper/h11).
+
+It aims to be a very simple synchronous web server that should work for a lot of projects that do not require multiple thousands of requests per second, although with a lot of cores and threads it can actually achieve about 10,000 requests per second on an untuned Linux system.
+
+## Architecture
+
+- Thread-per-connection (no thread pool), **no async**
+- Uses a pure Python HTTP/1.1 library (h11)
+- `socket` from the standard library for the actual TCP reading/writing
+- Single SQLite database thread (using `sqlite3` from the standard library), other threads simply send Python functions through a queue for it to execute
+
+## Quick start
+
+Ensure you are using a **free-threaded** build of Python, see [documentation here](https://docs.python.org/3/howto/free-threading-python.html). If using [`uv`](https://github.com/astral-sh/uv), which I highly recommend, you could use `uv python pin 3.14t` (where the `t` stands for the free-threaded version).
+
+Then, install `freetser` from PyPI with `uv add freetser`. 
+
+Finally, create a Python script (e.g. `main.py`) with the following code:
+
+```python
+import logging
+
+from freetser import (
+    Request,
+    Response,
+    ServerConfig,
+    Storage,
+    setup_logging,
+    start_server,
+)
+from freetser.server import StorageQueue
+
+logger = logging.getLogger("freetser.handler")
+
+def handler(req: Request, store_queue: StorageQueue | None) -> Response:
+    if req.path == "/":
+        return Response.text("Hello world!")
+
+    return Response.text("Not found!", status_code=404)
+
+
+def main():
+    listener = setup_logging()
+    listener.start()
+
+    config = ServerConfig(port=8000)
+    try:
+        start_server(config, handler)
+    except KeyboardInterrupt:
+        print("\nShutting down...")
+    finally:
+        listener.stop()
+
+
+if __name__ == "__main__":
+    main()
+```
+
+Then if you do `uv run main.py`, it will start the server on the default port of 8000.
+
+## Using the built-in storage
+
+`freetser` provides a built-in key-value (KV) store built on top of SQLite. It is not designed for speed, but for simplicity. First, define a database routine:
+
+```python
+def get_or_create(store: Storage) -> str:
+    key = "my_user_email"
+    result = store.get("USERS", key)
+    if result is None:
+        value = b"my.user@freetser.com"
+        store.add("USERS", key, value, 0)
+        return f"Created: {key}\n"
+    else:
+        value, counter = result
+        return f"Found: {key}, counter={counter}\n"
+```
+
+A database routine is simply a Python function or lambda that takes a `Storage` argument. Then, in your handler, call `result = store_queue.execute(get_or_create)`. The server will then execute this function on the database thread in a transaction, ensuring it either succeeds or fails. 
+
+This has some important consequences:
+- If any non-expected database error occurs (i.e. it does not derive from `StorageError`), the database thread will crash and the server will have to be restarted.
+- Therefore, you should **not** throw when you encounter application errors inside the routine, but instead return a value and handle the error in the handler. You can even just raise the error there, as when errors occur in the handler the server will simply return a 500 Internal Server Error but not crash (since the error is raised in the connection thread). 
+- Furthermore, try to only perform simple logic in the routines. Since we only have 1 database thread, all other threads have to wait on your routine to finish. So don't make any HTTP calls or other blocking requests. Put those in the handler instead. If this is a limitation, **don't use this library**. This library is explicitly not designed for highly concurrent use cases or high performance applications with hundreds of thousands of users. However, it should handle thousands just fine.
+
+For more examples, see `main.py` in the tests directory or check out the tests themselves.
+
+## Benchmarks
+
+In some basic stress testing on a local machine, we found that requests basically always take around 41-42 ms, giving a basic 25 requests per second. Note that we always perform at least a single SQLite operation, so every request has to go through the database thread.
+
+However, throughput can rise all the way to 5500 requests per second (using 300 request threads firing off requests on a keep-alive connection) without any real hit to latency, with requests still taking around 43 ms to complete on average (and at most 160 ms, hats off to the OS scheduler). From that point on, average request times start to climb as you add threads.
+
+Using 750 threads, throughput reaches 10,000 requests per second with an average request taking 53 ms. Using 1000 threads barely helps as throughput starts to level off rapidly, reaching 10,900 requests per second. 1200 threads wasn't possible to test without tuning OS settings.
+
+Benchmark machine specs: Intel Core Ultra 7 155H (22 vCPUs), Linux 6.17, 32GB LPDDR5x-7467 memory
+
+## Background
+
+I wanted to minimize dependencies and use the standard library's sqlite3 interface. However, sqlite3 is not made for async. Therefore, I wanted a synchronous web server. However, while there exists projects like Flask and Bottle, I simply could not grok how to easily integrate them with sqlite3. Furthermore, they are not designed to utilize Python's recent free-threaded build. 
+
+Most of all, I wanted a project where everyone can read the code and understand what it's doing, while also providing a built-in storage mechanism so you can use it for small-scale production use cases.

freetser-0.1.0/pyproject.toml

@@ -0,0 +1,36 @@
+[build-system]
+requires = ["uv_build>=0.9.11,<0.10.0"]
+build-backend = "uv_build"
+
+[project]
+name = "freetser"
+version = "0.1.0"
+description = "A free-threaded HTTP server built on top of h11"
+authors = [
+    { name = "Tip ten Brink", email = "tip@tenbrinkmeijs.com" },
+]
+readme = "README.md"
+requires-python = ">=3.14"
+dependencies = [
+    "h11>=0.16.0,<0.17.0",
+]
+
+[dependency-groups]
+dev = [
+    "basedpyright>=1.34.0",
+    "httpx>=0.28.1",
+    "pytest>=9.0.1",
+    "ruff>=0.14.6",
+]
+
+[tool.basedpyright]
+typeCheckingMode = "standard"
+pythonVersion = "3.14"
+include = ["src", "tests"]
+exclude = ["**/__pycache__", ".venv", "**/.venv"]
+
+[tool.ruff]
+target-version = "py314"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

freetser-0.1.0/src/freetser/__init__.py

@@ -0,0 +1,23 @@
+from .server import (
+    Request,
+    Response,
+    ServerConfig,
+    setup_logging,
+    start_server,
+)
+from .storage import (
+    EntryAlreadyExists,
+    Storage,
+    StorageError,
+)
+
+__all__ = [
+    "start_server",
+    "ServerConfig",
+    "Request",
+    "Response",
+    "setup_logging",
+    "Storage",
+    "StorageError",
+    "EntryAlreadyExists",
+]

freetser-0.1.0/src/freetser/server.py

@@ -0,0 +1,413 @@
+import json
+import logging
+import queue
+import socket
+import sys
+import threading
+from dataclasses import dataclass, field
+from logging.handlers import QueueHandler, QueueListener
+from pathlib import Path
+from queue import SimpleQueue
+from typing import Callable, Optional, cast
+
+import h11
+
+import freetser.storage as storage
+
+MAX_RECV = 2**16
+logger = logging.getLogger("freetser.server")
+
+
+@dataclass
+class ServerConfig:
+    host: str = "127.0.0.1"
+    port: int = 8000
+    max_header_size: int = 16 * 1024
+    max_body_size: int = 2 * 1024 * 1024
+    # Parameter passed to `socket.listen()`
+    listen_backlog: int = 1024
+    # Path to sqlite database file, will be created if it does not exist
+    db_file: str | None = None
+    # All tables that must be present, will be created if they do not exist
+    db_tables: list[str] | None = None
+
+
+@dataclass
+class Request:
+    method: str
+    path: str
+    headers: list[tuple[bytes, bytes]]
+    body: bytes
+
+
+@dataclass
+class Response:
+    status_code: int
+    headers: list[tuple[bytes, bytes]]
+    body: bytes
+
+    @staticmethod
+    def text(content: str, status_code: int = 200) -> "Response":
+        body = content.encode("utf-8")
+        return Response(
+            status_code=status_code,
+            headers=[
+                (b"Content-Type", b"text/plain; charset=utf-8"),
+                (b"Content-Length", str(len(body)).encode("ascii")),
+            ],
+            body=body,
+        )
+
+    @staticmethod
+    def empty(
+        headers: list[tuple[bytes, bytes]] | None = None, status_code: int = 200
+    ) -> "Response":
+        if headers is None:
+            headers = []
+        headers.append(
+            (b"Content-Length", "0".encode("ascii")),
+        )
+        return Response(status_code=status_code, headers=headers, body=b"")
+
+    @staticmethod
+    def json(
+        content,
+        headers: list[tuple[bytes, bytes]] | None = None,
+        status_code: int = 200,
+    ) -> "Response":
+        if headers is None:
+            headers = []
+        body = json.dumps(content).encode("utf-8")
+        headers.append(
+            (b"Content-Length", str(len(body)).encode("ascii")),
+        )
+        headers.append(
+            (b"Content-Type", b"application/json"),
+        )
+        return Response(status_code=status_code, headers=headers, body=body)
+
+
+@dataclass
+class ConnectionContext:
+    client_socket: socket.socket
+    client_address: tuple
+    store_queue: StorageQueue | None
+    config: ServerConfig
+
+
+def setup_logging() -> QueueListener:
+    """Configures non-blocking logging via QueueHandler/QueueListener."""
+    log_queue = queue.SimpleQueue()
+    queue_handler = QueueHandler(log_queue)
+
+    root = logging.getLogger()
+    root.setLevel(logging.INFO)
+    for h in root.handlers[:]:
+        root.removeHandler(h)
+    root.addHandler(queue_handler)
+
+    console_handler = logging.StreamHandler(sys.stdout)
+    console_handler.setFormatter(logging.Formatter("[%(threadName)s] %(message)s"))
+
+    listener = QueueListener(log_queue, console_handler)
+    return listener
+
+
+type Handler = Callable[[Request, StorageQueue | None], Response]
+
+
+def handle_client(ctx: ConnectionContext, handler: Handler):
+    logger.info(f"Connection from {ctx.client_address}")
+    conn = h11.Connection(
+        h11.SERVER, max_incomplete_event_size=ctx.config.max_header_size
+    )
+
+    try:
+        while True:
+            try:
+                # This is where we actually handle the request and response
+                if not handle_request_response(conn, ctx, handler):
+                    break
+
+                if (
+                    conn.our_state is h11.MUST_CLOSE
+                    or conn.their_state is h11.MUST_CLOSE
+                ):
+                    break
+
+                if conn.our_state is h11.DONE and conn.their_state is h11.DONE:
+                    conn.start_next_cycle()
+                else:
+                    break
+            except h11.RemoteProtocolError as e:
+                logger.error(f"Protocol error: {e}")
+                send_error_response(conn, ctx, 400, f"Bad Request: {e}")
+                break
+    except Exception as e:
+        logger.error(f"Unexpected error: {e}")
+    finally:
+        ctx.client_socket.close()
+        logger.info("Connection closed")
+
+
+def handle_request_response(
+    conn: h11.Connection, ctx: ConnectionContext, handler: Handler
+) -> bool:
+    event = get_next_event(conn, ctx.client_socket)
+    if event is None:
+        logger.debug("No event, ending request/response")
+        return False
+
+    if isinstance(event, h11.ConnectionClosed):
+        return False
+
+    if not isinstance(event, h11.Request):
+        raise Exception(f"Unexpected event: {event}!")
+
+    if event.http_version != b"1.1":
+        logger.debug(f"Rejecting HTTP/{event.http_version.decode()}")
+        send_error_response(conn, ctx, 505, "HTTP Version Not Supported")
+        return False
+
+    logger.info(f"{event.method.decode()} {event.target.decode()}")
+
+    if conn.they_are_waiting_for_100_continue:
+        logger.debug("Sending 100 Continue")
+        ctx.client_socket.sendall(
+            conn.send(h11.InformationalResponse(status_code=100, headers=[]))
+        )
+
+    try:
+        request_body = read_request_body(conn, ctx)
+    except ValueError as e:
+        logger.error(f"Body too large: {e}")
+        send_error_response(conn, ctx, 413, f"Payload Too Large: {e}")
+        return False
+
+    req = Request(
+        method=event.method.decode(),
+        path=event.target.decode(),
+        headers=list(event.headers),
+        body=request_body,
+    )
+
+    # Call the actual request handler that determines the response
+    try:
+        resp = handler(req, ctx.store_queue)
+    except Exception as e:
+        logger.error(f"Handler error: {e}")
+        send_error_response(conn, ctx, 500, "Internal Server Error")
+        # Close connection in case of internal server error
+        return False
+
+    send_response(conn, ctx, resp)
+    return True
+
+
+def get_next_event(conn: h11.Connection, sock: socket.socket) -> Optional[h11.Event]:
+    while True:
+        event = conn.next_event()
+        # We shouldn't ever be paused here because then we didn't properly call start_next_cycle
+        assert event is not h11.PAUSED
+        if event is h11.NEED_DATA:
+            try:
+                data = sock.recv(MAX_RECV)
+                # `receive_data` sees an empty `bytes` object as EOF, which matches `recv`
+                conn.receive_data(data)
+            except Exception as e:
+                logger.error(f"Socket error: {e}")
+                return None
+        else:
+            # We know it has to be Event in this case
+            # Unfortunately the 'sentinel' stuff means the type checker cannot narrow properly
+            return cast(h11.Event, event)
+
+
+def read_request_body(conn: h11.Connection, ctx: ConnectionContext) -> bytes:
+    """Throws ValueError if max body size is exceeded."""
+    body_parts = []
+    total_size = 0
+    while True:
+        event = get_next_event(conn, ctx.client_socket)
+        if event is None:
+            break
+        if isinstance(event, h11.Data):
+            total_size += len(event.data)
+            if total_size > ctx.config.max_body_size:
+                raise ValueError(f"Exceeded limit {ctx.config.max_body_size}")
+            body_parts.append(event.data)
+        elif isinstance(event, h11.EndOfMessage):
+            break
+    return b"".join(body_parts)
+
+
+def send_error_response(
+    conn: h11.Connection, ctx: ConnectionContext, status_code: int, message: str
+):
+    if conn.our_state not in {h11.IDLE, h11.SEND_RESPONSE}:
+        return
+    body = f"{status_code} Error: {message}\n".encode("utf-8")
+    try:
+        ctx.client_socket.sendall(
+            conn.send(
+                h11.Response(
+                    status_code=status_code,
+                    headers=[
+                        (b"Content-Type", b"text/plain; charset=utf-8"),
+                        (b"Content-Length", str(len(body)).encode("ascii")),
+                        (b"Connection", b"close"),
+                    ],
+                )
+            )
+        )
+        ctx.client_socket.sendall(conn.send(h11.Data(data=body)))
+        ctx.client_socket.sendall(conn.send(h11.EndOfMessage()))
+    except Exception as e:
+        logger.error(f"Send error: {e}")
+
+
+def send_response(conn: h11.Connection, ctx: ConnectionContext, response: Response):
+    try:
+        ctx.client_socket.sendall(
+            conn.send(
+                h11.Response(status_code=response.status_code, headers=response.headers)
+            )
+        )
+        ctx.client_socket.sendall(conn.send(h11.Data(data=response.body)))
+        ctx.client_socket.sendall(conn.send(h11.EndOfMessage()))
+    except Exception as e:
+        logger.error(f"Send error: {e}")
+
+
+class UnsetType:
+    """Sentinel value indicating that a value has not been set yet."""
+
+    def __repr__(self):
+        return "<UNSET>"
+
+
+UNSET = UnsetType()
+
+
+class StorageQueue:
+    queue: SimpleQueue
+
+    def __init__(self):
+        self.queue = SimpleQueue()
+
+    def execute[T](self, procedure: Callable[[storage.Storage], T]) -> T:
+        """Execute the given function on the storage thread. Can raise a StorageException, in which case the execution was rolled back."""
+        item: QueueItem[T] = QueueItem(procedure=procedure)
+        self.queue.put(item)
+        item.event.wait()
+        # StorageException is caught by the database thread and returned
+        if item.exception is not None:
+            raise item.exception
+        if isinstance(item.to_return, UnsetType):
+            raise RuntimeError("Event signaled but value not set")
+        return item.to_return
+
+
+@dataclass
+class QueueItem[T]:
+    procedure: Callable[[storage.Storage], T]
+    # The `field` is important, since otherwise we share a singel event for all items
+    event: threading.Event = field(default_factory=threading.Event)
+    to_return: T | UnsetType = UNSET
+    exception: storage.StorageError | None = None
+
+
+def run_store(store_queue: StorageQueue, db_file: str, db_tables: list[str] | None):
+    if db_file == ":memory:":
+        # Special string that opens a new database in memory
+        path = db_file
+    else:
+        # Get the absolute path of the parent and then rejoin to make sure what we show is what is
+        # actually used.
+        path = Path(db_file)
+        path_parent = path.parent.resolve(strict=True)
+        path = path_parent.joinpath(path.parts[-1])
+    store = storage.Storage(db_path=path, tables=db_tables)
+    logger.info(f"Opened SQLite database at {path}.")
+    while True:
+        try:
+            # We put a timeout just so that we occasionally do something in this thread
+            item = store_queue.queue.get(block=True, timeout=0.1)
+        except queue.Empty:
+            continue
+
+        if not isinstance(item, QueueItem):
+            continue
+        store.conn.execute("BEGIN IMMEDIATE")
+        try:
+            value = item.procedure(store)
+        except storage.StorageError as e:
+            # Rollback the transaction for recoverable errors
+            store.conn.rollback()
+            # Return the error to the caller instead of crashing the storage thread
+            item.exception = e
+            item.event.set()
+            continue
+        except Exception as e:
+            # Still try to rollback if we can
+            store.conn.rollback()
+            raise e
+
+        store.conn.commit()
+        item.to_return = value
+        item.event.set()
+
+
+def start_server(
+    config: ServerConfig,
+    handler: Handler,
+    ready_event: threading.Event | None = None,
+):
+    """Start the HTTP server and begin accepting connections.
+
+    Args:
+        config: Server configuration options.
+        handler: Function called to handle each request and produce a response.
+        ready_event: If provided, this event is set once the server is ready to
+            accept connections (after socket binding and before the accept loop).
+    """
+    server_socket = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+    server_socket.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
+    server_socket.bind((config.host, config.port))
+    server_socket.listen(config.listen_backlog)
+
+    logger.info(f"Server listening on {config.host}:{config.port}")
+    logger.info(f"Limits: Header={config.max_header_size}, Body={config.max_body_size}")
+
+    # We run 1 thread that has access to the SQLite database
+    # This ensures every operation is atomic
+    # Procedures are sent through the `store_queue`
+    # `daemon=True` ensures that we do not wait for the thread to finish when exiting
+    if config.db_file is not None:
+        store_queue = StorageQueue()
+        threading.Thread(
+            target=run_store,
+            args=(store_queue, config.db_file, config.db_tables),
+            daemon=True,
+        ).start()
+    else:
+        store_queue = None
+
+    if ready_event is not None:
+        ready_event.set()
+
+    try:
+        # This is the main accept loop, we create a new thread for every new connection
+        while True:
+            try:
+                client, addr = server_socket.accept()
+                ctx = ConnectionContext(client, addr, store_queue, config)
+                threading.Thread(
+                    target=handle_client, args=(ctx, handler), daemon=True
+                ).start()
+            except Exception as e:
+                logger.error(f"Accept error: {e}")
+    except KeyboardInterrupt:
+        pass
+    finally:
+        server_socket.close()

freetser-0.1.0/src/freetser/storage.py

@@ -0,0 +1,169 @@
+import logging
+import sqlite3
+from os import PathLike
+
+logger = logging.getLogger("freetser.storage")
+
+
+def check_integrity_error(
+    e: sqlite3.IntegrityError, column: str, category: str
+) -> bool:
+    """For column 'email' in table 'user', 'user.email' would be the column. For category, at least 'unique' works."""
+    assert isinstance(e.args[0], str)
+    return column in e.args[0] and category in e.args[0].lower()
+
+
+class StorageError(Exception):
+    """Base exception for storage errors."""
+
+    pass
+
+
+class EntryAlreadyExists(StorageError):
+    """Raised when trying to add a key that already exists."""
+
+    pass
+
+
+class Storage:
+    """
+    Creates the necessary tables and sets up connections.
+    """
+
+    conn: sqlite3.Connection
+
+    def __init__(self, db_path: str | PathLike[str], tables: list[str] | None = None):
+        # Set persistent settings (WAL mode persists across connections)
+        # And create tables
+        # We use LEGACY_TRANSACTION_CONTROL so that we can use isolation_leve=None
+        # This allows us to manually perform transaction control so there are no transactions
+        # implicitly opened and we can avoid "database is locked" errors when readers upgrade to
+        # writers.
+        conn = sqlite3.connect(
+            db_path,
+            autocommit=sqlite3.LEGACY_TRANSACTION_CONTROL,  # pyright: ignore [reportArgumentType]
+            isolation_level=None,
+        )
+        conn.execute("PRAGMA journal_mode = WAL;")
+        conn.execute("PRAGMA synchronous = NORMAL;")
+        conn.execute("PRAGMA cache_size = -64000;")
+        conn.execute("PRAGMA busy_timeout = 500;")
+        conn.commit()
+        if tables:
+            conn.execute("BEGIN IMMEDIATE")
+            for table in tables:
+                conn.execute(f"""
+                    CREATE TABLE IF NOT EXISTS {table} (
+                        key TEXT PRIMARY KEY,
+                        counter INTEGER NOT NULL,
+                        expiration INTEGER NOT NULL,
+                        value BLOB NOT NULL
+                    ) STRICT;
+                """)
+            conn.commit()
+
+        self.conn = conn
+
+    def close(self):
+        self.conn.close()
+
+    def get(
+        self, table_name: str, key: str, timestamp=None
+    ) -> tuple[bytes, int] | None:
+        """
+        Retrieve a value and its version counter.
+        """
+        cursor = self.conn.execute(
+            f"SELECT value, counter, expiration FROM {table_name} WHERE key = ?", (key,)
+        )
+        row = cursor.fetchone()
+        if row is None:
+            return None
+
+        expiration: int = row[2]
+        # If timestamp is provided, the expiration is set to positive and if expired, return None
+        if timestamp is not None and expiration > 0 and timestamp > expiration:
+            return None
+
+        return row[0], row[1]
+
+    def add(
+        self, table_name: str, key: str, value: bytes, expires_at=0, timestamp=None
+    ) -> None:
+        """
+        Add a new key-value pair.
+        If timestamp is provided and an entry exists but is expired, overwrite it.
+        """
+
+        # Validate that we're not adding an already-expired entry
+        if timestamp is not None and expires_at > 0 and timestamp > expires_at:
+            raise ValueError(
+                f"Cannot add entry that is already expired: expires_at={expires_at} < timestamp={timestamp}"
+            )
+
+        if timestamp is None:
+            # Simple insert without expiration check
+            try:
+                self.conn.execute(
+                    f"INSERT INTO {table_name} (key, value, counter, expiration) VALUES (?, ?, 0, ?)",
+                    (key, value, expires_at),
+                )
+            except sqlite3.IntegrityError as e:
+                self.conn.rollback()
+                if check_integrity_error(e, f"{table_name}.key", "unique"):
+                    raise EntryAlreadyExists(f"Key already exists: {key}") from e
+                raise e
+        else:
+            # Insert with expiration check - allow overwriting expired entries
+            cursor = self.conn.execute(
+                f"""
+                INSERT INTO {table_name} (key, value, counter, expiration)
+                VALUES (?, ?, 0, ?)
+                ON CONFLICT(key) DO UPDATE
+                SET value = excluded.value,
+                    counter = 0,
+                    expiration = excluded.expiration
+                WHERE expiration > 0 AND ? > expiration
+                RETURNING key
+                """,
+                (key, value, expires_at, timestamp),
+            )
+            if cursor.fetchone() is None:
+                # Conflict occurred but WHERE clause prevented update (key exists and not expired)
+                raise EntryAlreadyExists(f"Key already exists: {key}")
+
+    def update(
+        self,
+        table_name: str,
+        key: str,
+        value: bytes,
+        counter: int,
+        expires_at=0,
+        assert_updated: bool = True,
+    ) -> bool:
+        cursor = self.conn.execute(
+            f"""
+            UPDATE {table_name}
+            SET value = ?, counter = counter + 1, expiration = ?
+            WHERE key = ? AND counter = ?
+            """,
+            (value, expires_at, key, counter),
+        )
+        result = cursor.rowcount == 1
+        if assert_updated:
+            assert result
+        return result
+
+    def delete(self, table_name: str, key: str) -> bool:
+        cursor = self.conn.execute(f"DELETE FROM {table_name} WHERE key = ?", (key,))
+        return cursor.rowcount == 1
+
+    def list_keys(self, table_name: str) -> list[str]:
+        cursor = self.conn.execute(f"SELECT key FROM {table_name}")
+        result = [row[0] for row in cursor.fetchall()]
+        return result
+
+    def clear(self, table_name: str) -> None:
+        """Remove all entries from the table."""
+
+        self.conn.execute(f"DELETE FROM {table_name}")