PyMkDB 0.1.0__py3-none-any.whl

pymkdb/__init__.py

@@ -0,0 +1,6 @@
+"""
+PyMkDB — Python client SDK and server package for MkDB.
+"""
+
+__version__ = "0.1.0"
+__author__ = "MNG"

pymkdb/cli.py

@@ -0,0 +1,57 @@
+"""
+pymkdb.cli — console entry point for the `mkdb` command.
+
+Usage:
+    mkdb [PATH_TO_DB]          Start the server pointing at a database directory
+    mkdb [PATH_TO_DB] -c       Generate a default config.json in that directory
+"""
+
+import os
+import sys
+
+
+def main():
+    from colorama import Fore
+    from src.db import mkdb
+    from src.config.db import mkdb_config
+    from src.filing import read_json, write_json
+    from src.runtime import runtime_settings
+
+    print(f"""{Fore.CYAN}
+    ╔═══════════════════════════════════════╗
+    ║                                       ║
+    ║             Initializing              ║
+    ║                 MkDB                  ║
+    ║                                       ║
+    ╚═══════════════════════════════════════╝
+    {Fore.RESET}""")
+
+    try:
+        print("Initialized CWD:", os.getcwd())
+        pointer = sys.argv[1] if len(sys.argv) > 1 else runtime_settings.args.config
+        print("Pointing to:", pointer)
+        print(f"{Fore.CYAN}Reading Config...{Fore.RESET}")
+        if not pointer.endswith(".json"):
+            os.chdir(pointer)
+        CONFIG = read_json(runtime_settings.args.config)
+    except FileNotFoundError:
+        CONFIG = {}
+        if "-c" in sys.argv or "--generate-config" in sys.argv:
+            print(f"{Fore.GREEN}Generating default config file at "
+                  f"{runtime_settings.args.config}{Fore.RESET}")
+            write_json(runtime_settings.args.config, mkdb_config().json)
+            sys.exit(0)
+        print(f"{Fore.YELLOW}Config file not found at {runtime_settings.args.config}")
+        print(f"{Fore.BLUE}Use a path to a db directory or -c to generate a "
+              f"new config.{Fore.RESET}")
+        sys.exit(1)
+    except Exception as e:
+        print(f"{Fore.RED}Error loading config: {e}{Fore.RESET}")
+        sys.exit(1)
+
+    DATA_BASE = mkdb(CONFIG)
+    DATA_BASE.run()
+
+
+if __name__ == "__main__":
+    main()

pymkdb-0.1.0.dist-info/METADATA

@@ -0,0 +1,86 @@
+Metadata-Version: 2.4
+Name: PyMkDB
+Version: 0.1.0
+Summary: A log-structured, partitioned NoSQL database engine with full-text search, numeric indexes, and dual TCP/HTTP protocols.
+Author: MNG
+License: MIT
+Project-URL: Homepage, https://github.com/MNG/MkDB
+Project-URL: Repository, https://github.com/MNG/MkDB
+Keywords: database,nosql,document-store,full-text-search,log-structured
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Database
+Classifier: Topic :: Database :: Database Engines/Servers
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: colorama>=0.4.6
+Requires-Dist: reedsolo>=1.7.0
+
+# MkDB
+
+MkDB is a Custom Log-Structured Merge & Partitioned Redundant Storage Engine built entirely in Python. It provides a robust, highly-available NoSQL/Document database experience with secondary indexing, full-text search, and dual-protocol network access.
+
+## Architecture Highlights
+
+- **Rolling Log Storage Engine**: Append-only storage format guaranteeing high write availability with safe background compaction.
+- **RAM Cache & Debounced Write Queue**: In-memory caching and debounced batching for extreme performance under high write load.
+- **Query Engine & Secondary Indexes**: Fully featured query evaluation including numeric range checks and tokenized full-text inverted indexes.
+- **Data Integrity**: Multi-disk mirroring and Reed-Solomon parity encoding for proactive self-healing and failover.
+- **Dual Protocols**: Accessible via high-speed, persistent TCP WebSockets or standard stateless REST HTTP endpoints.
+- **Web Administration UI**: Includes an embedded web control panel out-of-the-box (`/control` endpoint).
+
+## Project Structure
+
+- `src/db/`: The core database engine (storage primitives, RAM caching, query evaluator, auto-compaction and parity management).
+- `src/server/`: The networking boundary. Houses the TCP Socket and HTTP REST servers, as well as the web-based Control Panel.
+- `src/config/`: Configuration schemas for tailoring memory limits, storage thresholds, and cluster layout.
+- `sdk/`: The official `MkDBClient` for programmatic interaction from Python code.
+
+## Getting Started
+
+### Prerequisites
+- Python 3.10+
+- The database storage format is built into MkDB natively, but you'll need the following for advanced data integrity features (Reed-Solomon logic):
+  ```bash
+  pip install reedsolo
+  ```
+
+### Starting the Server
+MkDB operates as a CLI tool. Launch the engine by pointing it to your desired database directory (which must contain a `config.json` file configuring your stores and network bindings):
+```bash
+mkdb /path/to/your/db
+```
+Once running, the database will host both TCP socket and HTTP interfaces as specified in your `config.json`. The web control panel is accessible via your browser (check server output for the bound port, normally `http://localhost:<port>`).
+
+### Using the Python SDK
+The `MkDBClient` connects seamlessly to your database and abstracts the dual-protocol system:
+
+```python
+from sdk.mkdb_client import MkDBClient
+
+client = MkDBClient()
+client.connect(host="127.0.0.1", port=8080)
+
+# Writing a document (computes delta updates intelligently)
+client.set(
+    store="products",
+    record_id="prod_001",
+    data={"name": "Steel Bolt", "price": 9.99, "category": "fasteners"}
+)
+
+# Reading a document
+record = client.get("products", "prod_001")
+
+# Querying with filters
+results = client.query("products", filter={
+    "price": {"<=": 10.00},
+    "category": ["fasteners"]
+})
+```
+
+See the `docs/` folder for comprehensive guides on the Query Syntax and SDK Reference.

pymkdb-0.1.0.dist-info/RECORD

@@ -0,0 +1,54 @@
+pymkdb/__init__.py,sha256=tTWRC26zpfcuI2ejtTeFGbpKppN6DS7J7MXGnxpSMvQ,114
+pymkdb/cli.py,sha256=PHY4XJnmi5hoPF28F9qgytyyO9O9l_01mBr47my-Efk,2170
+sdk/__init__.py,sha256=VZALxUv5N8fhQFU04coWBy6DoqEPD0Yv0wE60R-Jo-k,12
+sdk/connection.py,sha256=vh9cTf-sYQvrF2qSiXMNw-HAtiaDujo7l6BvpINRFXQ,8445
+sdk/delta.py,sha256=55rdFZvYfVEEkClSaQY4DgqDGuRamxVFB7-D23BfvJo,641
+sdk/http_connection.py,sha256=g_YTcbfS3neybvaOBxQxAHMFLtI86ENIFz7iBC33MWw,7254
+sdk/mkdb_client.py,sha256=vCmfN9uT_XOMc8hvFhOEslZoZNCjiDoNGs7nk811zRQ,8271
+sdk/responses.py,sha256=707Hbm-8M6Z83kOocQ2UyAp7F3ko-xklLCycp8-BF5U,5020
+src/__init__.py,sha256=rM5xk_iNEOneevj9ArdMGCMFHUA7Ac9JfNHFVPuXW08,28
+src/config/db.py,sha256=y0qYO6ZLt7F487SuUsY4fBqZtB0tqCbDVI3ap0CH_3c,9674
+src/config/server.py,sha256=p8Bcy1twSItc2RvFErIlN17xjFeG1ZkMFJiqu5B6AC0,2030
+src/db/__init__.py,sha256=g2zrEwJTIrJyg7IY8oaw4MAE7uFQaOhDU3InfRot4IY,8495
+src/db/cache/__init__.py,sha256=frcCV1k9oG9oKj3dpUqdJg1PxRT2RSN_XKdLCPjaYaY,2
+src/db/cache/ram_cache.py,sha256=Odv6bNwIwVduywAMPKiNcAro9pS3Bi3GVlFrSdgQx9E,5916
+src/db/cache/write_queue.py,sha256=GECdwsOOrzlkqz_oWZOSMzhoPucelE9r-JYe2FxS-tk,6012
+src/db/maintenance/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+src/db/maintenance/compactor.py,sha256=uyFWOL8WQCBJ3QjxqpEdQcUFAcRLIQXYJJTt4UxdG0w,4596
+src/db/maintenance/task_scheduler.py,sha256=gWD0WMD3gI56HZyZxFvZk1ZnYpyUgKKaezhU7TOXwVc,2680
+src/db/objects/store.py,sha256=HKO5uBGss9DwfqpYDIqwqhCEuXTcD-z3d7MZxhyfwDA,12908
+src/db/parity/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+src/db/parity/parity_manager.py,sha256=JW2NVg7atDjFFkyeQy4v7BtHpUkiYDAA3lL8ulFUNoQ,8385
+src/db/query/__init__.py,sha256=frcCV1k9oG9oKj3dpUqdJg1PxRT2RSN_XKdLCPjaYaY,2
+src/db/query/full_text_index.py,sha256=j8UOdgxChWU0leTSIgkg59dLwd3DA0I5AUiFBjtd0hY,6455
+src/db/query/numeric_index.py,sha256=Rye0c5Ip5ZtC3jyqgL92AZIG0qeiTtCfi6TYjcjgbMU,7824
+src/db/query/query_engine.py,sha256=4_Fzi3nBrQxrqJ2GWJfCFqkTLL4niOQdNIUDSzvLBjM,13120
+src/db/query/tokenizer.py,sha256=MrKWv3jo35Za-YmC6Hkhh9-qwAE08OQupLxP3nDth0Y,1589
+src/db/query_workers/__init__.py,sha256=KHLEVFKnMYcU9xisLJkBw84uWwPqi0LqX8yts4VpRbM,515
+src/db/query_workers/dispatcher.py,sha256=7Du5ThvzKsGKkh1PG5fEawT1zyf-kVkG8CwjErlxqSI,12308
+src/db/query_workers/task.py,sha256=AcWAhNnDIWQJHvi36-6eSrH8qPp6vOEgDE4oUooxSZU,2199
+src/db/query_workers/worker.py,sha256=a9MtbgI3AJvbT9VZH3EbZsfug3jshg87dtInBEk-mh0,10413
+src/db/requesting/main.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+src/db/storage/__init__.py,sha256=frcCV1k9oG9oKj3dpUqdJg1PxRT2RSN_XKdLCPjaYaY,2
+src/db/storage/blob_store.py,sha256=7TEMQh43S7rG9m9xaFy1-NEEVr3yvTp6MsV-ktGKqYc,1843
+src/db/storage/index_manager.py,sha256=CBJNsHDA3SJF438mX1fEbKxxbCGpxbwadTr6dAUNG0I,3905
+src/db/storage/log_manager.py,sha256=uHKf3axUwvEKvkCun0_q4bwLglsy6VcuKwZrZBSJ6BA,4681
+src/db/storage/serializer.py,sha256=pQLj1_7u-aCCi8_Zs-2_ZHjBVENLMnlex-fK_SPA3V8,1186
+src/filing/__init__.py,sha256=SbJobACQxc77TVRrwxx52EF9MEX2ndD22hzZsu7lxXE,695
+src/objects/__init__.py,sha256=Di8e7nDXnpAFOaz0WnSLoY8pRZTH29M9ozOhoOT1jM4,6876
+src/runtime/__init__.py,sha256=nkBs06mYlUxJBjT_rkIiMZmeutHJLrHJsJiPt23zudY,459
+src/server/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+src/server/event_log.py,sha256=FJUFPVHlnALclorIh8U9oY5y1FKqXKML54ZR7_hUkfY,1805
+src/server/coms/actions.py,sha256=o4nR-aI1h6HG8mKi_KVtpwJIF8ddDvx-BEwQRSzIOwg,8212
+src/server/coms/http.py,sha256=5g4NcugfkrPPFSzfYLI_VoMV7d9W_1qN5IucSvzLPH8,1715
+src/server/coms/http_handlers.py,sha256=H3HAViE1WOkO0q_iA-88zUq97vWzXo7t0YrrcW7Zo7A,17740
+src/server/coms/metrics.py,sha256=OtfWiU4xFFhqewDCKTNuCi8kOy8EdLgCdiNXYEkzzUA,7683
+src/server/coms/socket.py,sha256=icwRpGcHpCg_hpJCHqO7sWUkveSJG_S9sDMLPmwpeqY,19470
+src/server/coms/socket_protocol.py,sha256=6-3PKsux6HNWeFN_aJRWxp4kYKlDnl15fFM4XlpjjM8,1738
+src/server/control/server.py,sha256=D_R595I7SOME57MBLr1FdKPQ_3mEmrDXSSLIZs2pNyk,15802
+src/server/control/api/actions.py,sha256=ScLMaoTJW6rkOYBArNW2H_IUChuZ8LYivHKKapWzsWA,40751
+pymkdb-0.1.0.dist-info/METADATA,sha256=ZGNeM3gMJaWRi4QA3RRscjHPyU6A5lYFcnixbgM4sGc,3974
+pymkdb-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+pymkdb-0.1.0.dist-info/entry_points.txt,sha256=OaR65dAk0Ctb2rAFKwqjCcr5NXAvxX_TPcDophjvE-I,41
+pymkdb-0.1.0.dist-info/top_level.txt,sha256=nSypT91Rm-kq1NIv25tTLerFJt1RY1lzbQNzSTdg6FE,15
+pymkdb-0.1.0.dist-info/RECORD,,

pymkdb-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

pymkdb-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+mkdb = pymkdb.cli:main

pymkdb-0.1.0.dist-info/top_level.txt

@@ -0,0 +1,3 @@
+pymkdb
+sdk
+src

sdk/__init__.py

@@ -0,0 +1 @@
+# MkDB SDK

sdk/connection.py

@@ -0,0 +1,225 @@
+"""
+Low-level persistent TCP connection to a MkDB socket server.
+
+Wire format: 4-byte big-endian uint32 length + UTF-8 JSON payload.
+Mirrors src/server/coms/socket_protocol.py (client-side copy).
+"""
+
+import json
+import socket
+import struct
+import threading
+import uuid
+from typing import Callable, Optional
+
+
+MAX_FRAME = 10 * 1024 * 1024   # 10 MB
+
+
+def _recv_exact(sock: socket.socket, n: int) -> bytes:
+    buf = b""
+    while len(buf) < n:
+        chunk = sock.recv(n - len(buf))
+        if not chunk:
+            raise ConnectionError("Connection closed")
+        buf += chunk
+    return buf
+
+
+def _encode(payload: dict) -> bytes:
+    body = json.dumps(payload, ensure_ascii=False).encode("utf-8")
+    return struct.pack(">I", len(body)) + body
+
+
+def _decode(data: bytes) -> dict:
+    return json.loads(data.decode("utf-8"))
+
+
+class Connection:
+    """
+    Thread-safe persistent connection to MkDB.
+
+    Outbound: _send() serialises and writes to socket.
+    Inbound:  background _reader_loop() dispatches to registered handlers.
+    """
+
+    def __init__(self, host: str = "127.0.0.1", port: int = 9001,
+                 recv_timeout: float = 30.0,
+                 access: str = "R",
+                 username: str = "",
+                 password: str = ""):
+        self.host         = host
+        self.port         = port
+        self.recv_timeout = recv_timeout
+        self._access      = access.upper() if access.upper() in ("R", "W", "RW") else "R"
+        self._username    = username
+        self._password    = password
+        self._sock: Optional[socket.socket] = None
+        self._lock        = threading.Lock()
+        self._pending: dict[str, threading.Event] = {}     # correlation_id -> Event
+        self._results: dict[str, dict] = {}                # correlation_id -> response dict
+        self._push_handlers: list[Callable[[dict], None]] = []   # for server-push events
+        self._running  = False
+        self.can_read  = False
+        self.can_write = False
+
+    # ------------------------------------------------------------------
+    # Connect / disconnect
+    # ------------------------------------------------------------------
+
+    def connect(self) -> None:
+        sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+        sock.settimeout(self.recv_timeout)
+        sock.connect((self.host, self.port))
+
+        # ── Handshake ────────────────────────────────────────────────
+        perm = self._handshake_recv(sock)
+        if perm.get("type") != "permissions":
+            sock.close()
+            raise ConnectionError(f"Expected 'permissions', got: {perm}")
+
+        read_protected  = perm.get("read_protected", False)
+        write_protected = perm.get("write_protected", False)
+
+        # Declare desired access level
+        self._handshake_send(sock, {"access": self._access})
+
+        need_auth = (
+            (self._access in ("W", "RW") and write_protected)
+            or (self._access == "R" and read_protected)
+        )
+
+        if need_auth:
+            challenge = self._handshake_recv(sock)
+            if challenge.get("type") != "auth_required":
+                sock.close()
+                raise ConnectionError(f"Expected 'auth_required', got: {challenge}")
+            if not self._password:
+                sock.close()
+                raise PermissionError("Server requires authentication but no password provided")
+            self._handshake_send(sock, {
+                "type":     "auth",
+                "username": self._username,
+                "password": self._password,
+            })
+            result = self._handshake_recv(sock)
+            if result.get("type") == "error":
+                sock.close()
+                raise PermissionError(result.get("error", "Authentication failed"))
+            if result.get("type") != "auth_ok":
+                sock.close()
+                raise ConnectionError(f"Unexpected handshake response: {result}")
+            self.can_read  = result.get("can_read",  False)
+            self.can_write = result.get("can_write", False)
+        else:
+            ready = self._handshake_recv(sock)
+            if ready.get("type") == "error":
+                sock.close()
+                raise ConnectionError(ready.get("error", "Connection refused"))
+            self.can_read  = ready.get("can_read",  True)
+            self.can_write = ready.get("can_write", False)
+
+        self._sock    = sock
+        self._running = True
+        reader = threading.Thread(
+            target=self._reader_loop, daemon=True, name="MkDB-SDK-reader"
+        )
+        reader.start()
+
+    @staticmethod
+    def _handshake_send(sock: socket.socket, msg: dict) -> None:
+        body = json.dumps(msg).encode("utf-8")
+        sock.sendall(struct.pack(">I", len(body)) + body)
+
+    @staticmethod
+    def _handshake_recv(sock: socket.socket) -> dict:
+        hdr    = _recv_exact(sock, 4)
+        length = struct.unpack(">I", hdr)[0]
+        return json.loads(_recv_exact(sock, length).decode("utf-8"))
+
+    def close(self) -> None:
+        self._running = False
+        if self._sock:
+            try:
+                self._sock.close()
+            except Exception:
+                pass
+        self._sock = None
+
+    # ------------------------------------------------------------------
+    # Send / receive
+    # ------------------------------------------------------------------
+
+    def send(self, payload: dict) -> dict:
+        """
+        Send a request and block until the matching response arrives.
+        Returns the response dict.
+        """
+        correlation_id = str(uuid.uuid4())
+        payload["id"] = correlation_id
+        payload.setdefault("type", "request")
+
+        event = threading.Event()
+        with self._lock:
+            self._pending[correlation_id] = event
+
+        frame = _encode(payload)
+        with self._lock:
+            self._sock.sendall(frame)
+
+        event.wait(timeout=self.recv_timeout)
+        with self._lock:
+            result = self._results.pop(correlation_id, None)
+            self._pending.pop(correlation_id, None)
+        if result is None:
+            raise TimeoutError("No response received within timeout")
+        return result
+
+    def send_raw(self, payload: dict) -> None:
+        """Fire-and-forget (used for subscribe)."""
+        frame = _encode(payload)
+        with self._lock:
+            self._sock.sendall(frame)
+
+    def register_push_handler(self, handler: Callable[[dict], None]) -> None:
+        """Register a callback for server-push (ping, update, subscribed, disconnect)."""
+        self._push_handlers.append(handler)
+
+    # ------------------------------------------------------------------
+    # Reader loop (background thread)
+    # ------------------------------------------------------------------
+
+    def _reader_loop(self) -> None:
+        while self._running and self._sock:
+            try:
+                length_bytes = _recv_exact(self._sock, 4)
+                length = struct.unpack(">I", length_bytes)[0]
+                if length > MAX_FRAME:
+                    break   # protocol violation — disconnect
+                payload_bytes = _recv_exact(self._sock, length)
+                msg = _decode(payload_bytes)
+            except Exception:
+                break
+
+            msg_type = msg.get("type")
+            correlation_id = msg.get("id")
+
+            if msg_type == "response" and correlation_id:
+                with self._lock:
+                    event = self._pending.get(correlation_id)
+                    if event:
+                        self._results[correlation_id] = msg
+                        event.set()
+            elif msg_type == "ping":
+                # Respond with pong
+                try:
+                    self._sock.sendall(_encode({"type": "pong"}))
+                except Exception:
+                    break
+            else:
+                # Server-push: dispatch to registered handlers
+                for handler in self._push_handlers:
+                    try:
+                        handler(msg)
+                    except Exception:
+                        pass

sdk/delta.py

@@ -0,0 +1,19 @@
+"""
+Delta helpers — flatten nested dicts into dot-notation keys for MkDB writes.
+
+Example:
+    flatten({"product": {"name": "Widget", "price": 9.99}})
+    # → {"product.name": "Widget", "product.price": 9.99}
+"""
+
+
+def flatten(d: dict, prefix: str = "", sep: str = ".") -> dict:
+    """Recursively flatten a nested dict into dot-notation keys."""
+    result = {}
+    for key, value in d.items():
+        full_key = f"{prefix}{sep}{key}" if prefix else key
+        if isinstance(value, dict):
+            result.update(flatten(value, full_key, sep))
+        else:
+            result[full_key] = value
+    return result

sdk/http_connection.py

@@ -0,0 +1,180 @@
+"""
+HTTP transport for the MkDB SDK.
+
+Implements the same interface that Connection does (send / close / can_read /
+can_write / register_push_handler) but uses plain HTTP requests against the
+MkDB HTTP data-plane server instead of the persistent socket protocol.
+
+Limitations vs. socket transport:
+- No server-push / pub-sub (register_push_handler is a no-op).
+- Each call opens a new HTTP request (no persistent connection).
+- `send_raw` is a no-op (subscribe is not supported).
+"""
+
+import base64
+import json
+import urllib.request
+import urllib.error
+from typing import Callable, Optional
+
+
+class HttpConnection:
+    """HTTP client that mirrors the Connection interface."""
+
+    def __init__(
+        self,
+        host: str = "127.0.0.1",
+        port: int = 80,
+        recv_timeout: float = 30.0,
+        access: str = "RW",
+        username: str = "",
+        password: str = "",
+    ):
+        self.host         = host
+        self.port         = port
+        self.recv_timeout = recv_timeout
+        self._access      = access.upper()
+        self._username    = username
+        self._password    = password
+
+        # Mirrors Connection public attributes
+        self.can_read  = "R" in self._access
+        self.can_write = "W" in self._access
+
+        self._base_url  = f"http://{host}:{port}"
+        self._auth_header: Optional[str] = None  # populated in connect()
+
+    # ------------------------------------------------------------------
+    # Lifecycle (no persistent connection needed for HTTP)
+    # ------------------------------------------------------------------
+
+    def connect(self) -> None:
+        """Build auth header if credentials are provided; verify reachability."""
+        if self._username and self._password:
+            raw = f"{self._username}:{self._password}"
+            encoded = base64.b64encode(raw.encode()).decode()
+            self._auth_header = f"Basic {encoded}"
+        # Optional: hit /health to verify the server is up
+        try:
+            self._http_get("/health")
+        except Exception as exc:
+            raise ConnectionError(f"MkDB HTTP server unreachable at {self._base_url}: {exc}") from exc
+
+    def close(self) -> None:
+        """No persistent socket to close."""
+        pass
+
+    # ------------------------------------------------------------------
+    # Send (translate socket-style payload to HTTP calls)
+    # ------------------------------------------------------------------
+
+    def send(self, payload: dict) -> dict:
+        """
+        Translate a socket-style request dict into the appropriate HTTP call.
+
+        Supported actions: ping, read, write, delete, query.
+        """
+        action     = payload.get("action", "")
+        store      = payload.get("store", "")
+        record_id  = payload.get("record_id", "")
+        delta      = payload.get("delta", {})
+        filter_d   = payload.get("filter", {})
+        hydrate    = payload.get("hydrate", False)
+
+        if action == "ping":
+            data = self._http_get("/health")
+            return {"type": "response", "status": "ok", "data": data}
+
+        if action == "read":
+            if not store or not record_id:
+                return self._err("'store' and 'record_id' are required for read")
+            data = self._http_get(f"/data/{store}/{record_id}")
+            return {"type": "response", "status": "ok", "data": data}
+
+        if action == "write":
+            body = {"store": store, "record_id": record_id, "delta": delta}
+            data = self._http_post("/data", body)
+            return {"type": "response", "status": "ok", "data": data}
+
+        if action == "delete":
+            if not store or not record_id:
+                return self._err("'store' and 'record_id' are required for delete")
+            data = self._http_delete(f"/data/{store}/{record_id}")
+            return {"type": "response", "status": "ok", "data": data}
+
+        if action == "query":
+            body = {"store": store, "filter": filter_d, "hydrate": hydrate}
+            data = self._http_post("/query", body)
+            return {"type": "response", "status": "ok", "data": data}
+
+        return self._err(f"Action '{action}' is not supported over HTTP transport")
+
+    def send_raw(self, payload: dict) -> None:
+        """No-op — pub-sub subscribe is not available over HTTP."""
+        pass
+
+    def register_push_handler(self, handler: Callable[[dict], None]) -> None:
+        """No-op — server-push is not available over HTTP."""
+        pass
+
+    # ------------------------------------------------------------------
+    # HTTP helpers
+    # ------------------------------------------------------------------
+
+    def _headers(self, content_type: bool = False) -> dict:
+        h = {}
+        if self._auth_header:
+            h["Authorization"] = self._auth_header
+        if content_type:
+            h["Content-Type"] = "application/json; charset=utf-8"
+        return h
+
+    def _http_get(self, path: str) -> dict:
+        url = self._base_url + path
+        req = urllib.request.Request(url, headers=self._headers())
+        try:
+            with urllib.request.urlopen(req, timeout=self.recv_timeout) as resp:
+                body = json.loads(resp.read().decode("utf-8"))
+                return body.get("data", body)
+        except urllib.error.HTTPError as exc:
+            body = {}
+            try:
+                body = json.loads(exc.read().decode("utf-8"))
+            except Exception:
+                pass
+            raise RuntimeError(body.get("message", str(exc))) from exc
+
+    def _http_post(self, path: str, payload: dict) -> dict:
+        url = self._base_url + path
+        data = json.dumps(payload, ensure_ascii=False).encode("utf-8")
+        req = urllib.request.Request(url, data=data, headers=self._headers(content_type=True), method="POST")
+        try:
+            with urllib.request.urlopen(req, timeout=self.recv_timeout) as resp:
+                body = json.loads(resp.read().decode("utf-8"))
+                return body.get("data", body)
+        except urllib.error.HTTPError as exc:
+            body = {}
+            try:
+                body = json.loads(exc.read().decode("utf-8"))
+            except Exception:
+                pass
+            raise RuntimeError(body.get("message", str(exc))) from exc
+
+    def _http_delete(self, path: str) -> dict:
+        url = self._base_url + path
+        req = urllib.request.Request(url, headers=self._headers(), method="DELETE")
+        try:
+            with urllib.request.urlopen(req, timeout=self.recv_timeout) as resp:
+                body = json.loads(resp.read().decode("utf-8"))
+                return body.get("data", body)
+        except urllib.error.HTTPError as exc:
+            body = {}
+            try:
+                body = json.loads(exc.read().decode("utf-8"))
+            except Exception:
+                pass
+            raise RuntimeError(body.get("message", str(exc))) from exc
+
+    @staticmethod
+    def _err(message: str) -> dict:
+        return {"type": "response", "status": "error", "error": message}