messagefoundry 0.1.0__tar.gz

messagefoundry-0.1.0/.claude/settings.json

@@ -0,0 +1,81 @@
+{
+  "permissions": {
+    "allow": [
+      "PowerShell($env:QT_QPA_PLATFORM=\"offscreen\"; .venv\\\\Scripts\\\\python.exe -m pytest -q 2>&1 | Select-Object -Last 10)",
+      "PowerShell(git checkout main 2>&1)",
+      "PowerShell(git pull --ff-only 2>&1)",
+      "PowerShell(git switch -c logsearch-columns 2>&1)",
+      "PowerShell(.venv\\\\Scripts\\\\ruff.exe format messagefoundry tests 2>&1)",
+      "PowerShell(.venv\\\\Scripts\\\\ruff.exe check messagefoundry tests 2>&1)",
+      "PowerShell(.venv\\\\Scripts\\\\mypy.exe messagefoundry 2>&1)",
+      "PowerShell(\"--- check ---\")",
+      "PowerShell(\"--- mypy ---\")",
+      "PowerShell($env:QT_QPA_PLATFORM=\"offscreen\"; .venv\\\\Scripts\\\\python.exe -m pytest -q 2>&1 | Select-Object -Last 8)",
+      "PowerShell($env:QT_QPA_PLATFORM=\"offscreen\"; .venv\\\\Scripts\\\\ruff.exe format messagefoundry tests 2>&1 | Select-Object -Last 1; .venv\\\\Scripts\\\\ruff.exe check messagefoundry tests 2>&1 | Select-Object -Last 2; .venv\\\\Scripts\\\\mypy.exe messagefoundry 2>&1 | Select-Object -Last 2; .venv\\\\Scripts\\\\python.exe -m pytest -q 2>&1 | Select-Object -Last 4)"
+    ],
+    "deny": [
+      "Read(./.env)",
+      "Read(./.env.*)",
+      "Read(./secrets/**)",
+      "Read(./*.key)",
+      "Read(./*.pem)",
+      "Read(./*.pfx)",
+      "Read(./*.db)",
+      "Read(./*.db-wal)",
+      "Read(./*.db-shm)",
+      "Read(./bootstrap-admin.txt)",
+      "Edit(./.env)",
+      "Edit(./.env.*)",
+      "Edit(./secrets/**)",
+      "Edit(./*.db)",
+      "Write(./.env)",
+      "Write(./secrets/**)",
+      "Bash(rm -rf:*)",
+      "Bash(git push --force:*)",
+      "Bash(git push -f:*)",
+      "Bash(git reset --hard:*)",
+      "PowerShell(Remove-Item -Recurse -Force:*)",
+      "PowerShell(git push --force:*)",
+      "PowerShell(git push -f:*)",
+      "PowerShell(git reset --hard:*)"
+    ]
+  },
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "if": "Bash(git *)",
+            "command": "pwsh -NoProfile -File scripts/hooks/block-blanket-git-stage.ps1",
+            "timeout": 20,
+            "statusMessage": "Checking git staging"
+          }
+        ]
+      },
+      {
+        "matcher": "PowerShell",
+        "hooks": [
+          {
+            "type": "command",
+            "if": "PowerShell(git *)",
+            "command": "pwsh -NoProfile -File scripts/hooks/block-blanket-git-stage.ps1",
+            "timeout": 20,
+            "statusMessage": "Checking git staging"
+          }
+        ]
+      }
+    ],
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "pwsh -NoProfile -File scripts/worktree/session-context.ps1"
+          }
+        ]
+      }
+    ]
+  }
+}

messagefoundry-0.1.0/.gitattributes

@@ -0,0 +1,4 @@
+# Keep the dependency lockfiles LF on every platform so the CI sync-check (`uv export` +
+# `git diff --exit-code`) can't be tripped by Windows CRLF drift (DEP-1).
+uv.lock text eol=lf
+requirements.lock text eol=lf

messagefoundry-0.1.0/.github/CODEOWNERS

@@ -0,0 +1,19 @@
+# Code owners for MessageFoundry.
+# Listed owners are auto-requested for review when matching paths change.
+# See GOVERNANCE.md and MAINTAINERS.md for the roles behind these assignments.
+
+# Default owner for everything in the repo.
+*                                         @wshallwshall
+
+# --- Sensitive subsystems: steward review required even after more maintainers join ---
+/messagefoundry/auth/                     @wshallwshall
+/messagefoundry/store/                    @wshallwshall
+/messagefoundry/transports/               @wshallwshall
+/messagefoundry/api/security.py           @wshallwshall
+
+# Security, licensing, and the public-mirror publish/scan tooling.
+/docs/SECURITY.md                         @wshallwshall
+/docs/Secure_Development_Standards.md     @wshallwshall
+/scripts/publish/                         @wshallwshall
+/CLA.md                                   @wshallwshall
+/LICENSE                                  @wshallwshall

messagefoundry-0.1.0/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,41 @@
+---
+name: Bug report
+about: Report a problem with the MessageFoundry engine, console, or IDE tooling
+title: ''
+labels: bug
+assignees: ''
+---
+
+> ⚠️ **Never paste real PHI / patient data.** MessageFoundry processes HL7 in real
+> deployments — use **synthetic** messages only (`messagefoundry generate ...`) and redact
+> any IPs, hostnames, partner names, or message bodies before sharing. Security
+> vulnerabilities should be reported privately, not here — see
+> [SECURITY.md](../SECURITY.md).
+
+**Describe the bug**
+A clear and concise description of what the bug is.
+
+**To reproduce**
+Steps to reproduce the behavior — include the relevant config (Connection/Router/Handler) and a
+**synthetic** sample message where applicable:
+1. Configure '...'
+2. Send / poll '...'
+3. Observe '...'
+
+**Expected behavior**
+What you expected to happen.
+
+**Actual behavior / logs**
+What happened instead. Include the relevant log lines or stack trace (redact PHI and any
+host/partner identifiers).
+
+**Environment**
+- MessageFoundry version: <!-- `messagefoundry --version` -->
+- OS: <!-- e.g. Windows Server 2022 / Ubuntu 24.04 -->
+- Python version: <!-- `python --version` -->
+- Store backend: <!-- SQLite (default) / SQL Server (experimental) -->
+- Component: <!-- engine / console / IDE extension -->
+- Transport(s) involved: <!-- MLLP / file / database / REST / SOAP -->
+
+**Additional context**
+Anything else that helps — message type/trigger, whether it's reproducible, recent changes, etc.

messagefoundry-0.1.0/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,7 @@
+blank_issues_enabled: true
+contact_links:
+  - name: Report a security vulnerability
+    url: https://github.com/wshallwshall/MessageFoundry/security/advisories/new
+    about: >-
+      Please report security issues PRIVATELY via a GitHub security advisory, not as a
+      public issue. See SECURITY.md for the disclosure policy and response timeline.

messagefoundry-0.1.0/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,24 @@
+---
+name: Feature request
+about: Suggest an idea or enhancement for MessageFoundry
+title: ''
+labels: enhancement
+assignees: ''
+---
+
+**Is your feature request related to a problem? Please describe.**
+A clear and concise description of the problem. Ex. "When migrating from <engine> I need [...]"
+
+**Describe the solution you'd like**
+What you want to happen. If it's a new connector/transport, transform capability, or console/IDE
+feature, say so.
+
+**Area**
+Which part of the system does this touch?
+<!-- Connection/transport · Router/Handler · message store · API · console · IDE extension · docs -->
+
+**Describe alternatives you've considered**
+Any alternative solutions or workarounds you've considered.
+
+**Additional context**
+Add any other context, examples, or references (e.g. how Mirth/Corepoint/Rhapsody handle it).

messagefoundry-0.1.0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,29 @@
+<!-- Thanks for contributing to MessageFoundry! Please read CONTRIBUTING.md and GOVERNANCE.md first. -->
+
+## What this changes
+
+<!-- A short description of the change and the motivation. Link any related issue or ADR. -->
+
+Closes #
+
+## Type of change
+
+- [ ] Bug fix (a test reproducing the bug is included)
+- [ ] New Connection/transport or example Router/Handler
+- [ ] Documentation
+- [ ] Refactor / internal change
+- [ ] Architecture change (an ADR under `docs/adr/` is included or linked)
+
+## Checklist
+
+- [ ] I have read [CONTRIBUTING.md](../CONTRIBUTING.md) and will agree to the [CLA](../CLA.md) (the bot records it).
+- [ ] If this touches the reliability invariants, store/queue, staged pipeline, auth/RBAC, or the
+      code-first graph model, I **discussed it first** via an issue/ADR (see [GOVERNANCE.md](../GOVERNANCE.md)).
+- [ ] **No real PHI or customer data** anywhere in the diff, tests, fixtures, screenshots, or commit
+      messages — synthetic HL7 only (`python -m messagefoundry generate`).
+- [ ] Tests added/updated for new behavior.
+- [ ] Gates pass locally: `ruff check .`, `ruff format --check .`, `mypy messagefoundry`, and
+      `pytest -q` (`QT_QPA_PLATFORM=offscreen` for console tests). `python -m messagefoundry check` is green.
+- [ ] Uses **Connection / Router / Handler** vocabulary; no new declarative "channel" element; no
+      GUI/web-framework imports in the engine packages; no Black.
+- [ ] Docs updated if behavior or configuration changed.

messagefoundry-0.1.0/.github/SECURITY.md

@@ -0,0 +1,50 @@
+# Security Policy
+
+MessageFoundry is an HL7 v2.x integration engine that handles **PHI**. We take security
+reports seriously and appreciate responsible disclosure.
+
+## Supported versions
+
+The project is pre-1.0 and evolving rapidly; only the latest `main` is supported. Please
+verify a report against current `main` before filing.
+
+## Reporting a vulnerability
+
+**Do not open a public issue for a vulnerability.** Instead, report it privately:
+
+- Preferred: open a [GitHub private security advisory](https://github.com/wshallwshall/MessageFoundry/security/advisories/new)
+  ("Report a vulnerability"), or
+- Email the maintainer at the address on the GitHub profile.
+
+Please include: affected component (e.g. MLLP/file transport, store, API/auth, console),
+a description and impact, and reproduction steps or a proof of concept. Do **not** include
+real PHI — use synthetic HL7 (the `messagefoundry generate` corpus is ideal).
+
+We aim to acknowledge within a few business days and credit reporters who wish to be named once a
+fix is released.
+
+## Response & remediation timeline
+
+After we acknowledge a report, we triage it by severity and target these remediation windows
+(measured from triage; fixes are verified before a report is closed):
+
+| Severity | Target to remediate |
+|---|---|
+| Critical | ≤ 7 days |
+| High | ≤ 30 days |
+| Medium | ≤ 90 days |
+| Low | Best-effort |
+
+**Coordinated disclosure.** We practice coordinated disclosure: we ask that you give us a reasonable
+window to ship a fix before any public detail, and we publish details (and credit, if wanted) **once
+a fix is available**. We'll keep you updated on progress and agree the disclosure timing with you.
+These windows trace to the project's Secure Development Standards (§4.4 RV.2, Appendix A.5).
+
+## Scope notes
+
+- The engine binds `127.0.0.1` by default and requires authentication; the documented threat
+  model and current posture live in [`docs/SECURITY.md`](../docs/SECURITY.md). Findings are
+  rated both for today's localhost posture and for a future network-exposed deployment.
+- Configuration is **executed Python** (Routers/Handlers) from an admin-owned config directory;
+  the ability of a config author to run code in-process is by design, not a vulnerability — see
+  `docs/SECURITY.md` and `docs/SERVICE.md` for the trust boundary and required directory ACLs.

messagefoundry-0.1.0/.github/dependabot.yml

@@ -0,0 +1,17 @@
+# Dependabot: surface vulnerable / outdated dependencies and CI actions as PRs (CI-1 / DEP-1).
+# Until a committed lockfile lands, this is the primary signal for a known-CVE dependency.
+version: 2
+updates:
+  - package-ecosystem: "pip"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    open-pull-requests-limit: 10
+    groups:
+      python-deps:
+        patterns: ["*"]
+
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"

messagefoundry-0.1.0/.github/workflows/benchmark.yml

@@ -0,0 +1,217 @@
+# Throughput baseline (Gate #3 / WS-D) — on-demand only. Runs the reference sustainable-rate steps (the
+# open-loop end-to-end throughput finder) on each store backend, plus the active-passive failover profile on
+# the server-DB backends, on CI Linux + Docker PG/SQL Server containers (the reference config the
+# TUNING-BASELINE doc names). Each job uploads its METRICS-ONLY report JSON (no message bodies / control
+# ids — passes the publish forbidden-content guard); the numbers are transcribed into
+# docs/benchmarks/TUNING-BASELINE.md + committed under docs/benchmarks/results/.
+#
+# Manual: `gh workflow run benchmark.yml --ref <branch>` (heavy + container-bound, so never on push/PR).
+name: throughput-baseline
+
+on:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+env:
+  # A modest, documented fan-out for the reference run (each inbound → a couple of outbound deliveries),
+  # so the run characterizes a fan-out estate without the co-located DB container being swamped (the
+  # delivery path — a fresh connection per delivery + a server-DB round-trip per stage — is the ceiling).
+  MEFOR_LOAD_FANOUT: "2"
+  MEFOR_LOAD_RESULTS_FANOUT: "1"
+  MEFOR_LOAD_TRANSFORM: edit
+
+jobs:
+  baseline-sqlite:
+    name: baseline (sqlite)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6
+      - name: Set up Python
+        uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6
+        with:
+          python-version: "3.13"
+      - name: Install project (dev)
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+      - name: Environment stamp
+        run: |
+          mkdir -p out/load
+          { echo "## sqlite"; uname -a; python --version; python -c "import sqlite3,sys; print('sqlite', sqlite3.sqlite_version)"; git rev-parse HEAD; } | tee out/load/env-sqlite.txt
+      - name: Serve (SQLite) + reference rate-steps
+        env:
+          MEFOR_AUTH_ENABLED: "false"
+          MEFOR_LOAD_SINK_PORT: "2700"
+        run: |
+          set -o pipefail
+          python -m messagefoundry serve --config harness/config/load --env dev --db ./bench.db \
+            --host 127.0.0.1 --port 8765 > engine.log 2>&1 &
+          engine_pid=$!
+          for _ in $(seq 1 60); do curl -sf http://127.0.0.1:8765/health > /dev/null && break || sleep 0.5; done
+          set +e
+          python -m harness --load reference --engine http://127.0.0.1:8765 --sink-port 2700 \
+            --db-backend sqlite --report-json out/load/reference-sqlite.json --report-csv out/load/reference-sqlite.csv
+          set -e
+          kill "$engine_pid" 2>/dev/null || true
+          echo "===== engine log (tail) ====="; tail -40 engine.log || true
+      - name: Upload baseline report
+        if: always()
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
+        with:
+          name: baseline-sqlite
+          path: out/load/
+          if-no-files-found: ignore
+
+  baseline-postgres:
+    name: baseline (postgres)
+    runs-on: ubuntu-latest
+    services:
+      postgres:
+        image: postgres:16
+        env:
+          POSTGRES_PASSWORD: mefor
+          POSTGRES_DB: messagefoundry
+        ports:
+          - 5432:5432
+        options: >-
+          --health-cmd pg_isready --health-interval 10s --health-timeout 5s --health-retries 5
+    env:
+      MEFOR_STORE_BACKEND: postgres
+      MEFOR_STORE_SERVER: localhost
+      MEFOR_STORE_PORT: "5432"
+      MEFOR_STORE_DATABASE: messagefoundry
+      MEFOR_STORE_USERNAME: postgres
+      MEFOR_STORE_PASSWORD: mefor
+      MEFOR_STORE_POOL_SIZE: "5"
+      MEFOR_STORE_ENCRYPT: "false"  # plaintext to the container; the TLS-hardening guard needs the escape
+      MEFOR_ALLOW_INSECURE_TLS: "1"
+    steps:
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6
+      - name: Set up Python
+        uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6
+        with:
+          python-version: "3.13"
+      - name: Install project (dev + postgres)
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev,postgres]"
+      - name: Environment stamp
+        run: |
+          mkdir -p out/load
+          { echo "## postgres"; uname -a; python --version; psql --version 2>/dev/null || echo "psql n/a"; git rev-parse HEAD; } | tee out/load/env-postgres.txt
+      - name: Serve (Postgres) + reference rate-steps
+        env:
+          MEFOR_AUTH_ENABLED: "false"
+          MEFOR_LOAD_SINK_PORT: "2700"
+        run: |
+          set -o pipefail
+          python -m messagefoundry serve --config harness/config/load --env dev \
+            --host 127.0.0.1 --port 8765 > engine.log 2>&1 &
+          engine_pid=$!
+          for _ in $(seq 1 60); do curl -sf http://127.0.0.1:8765/health > /dev/null && break || sleep 0.5; done
+          set +e
+          python -m harness --load reference --engine http://127.0.0.1:8765 --sink-port 2700 \
+            --db-backend postgres --report-json out/load/reference-postgres.json --report-csv out/load/reference-postgres.csv
+          set -e
+          kill "$engine_pid" 2>/dev/null || true
+          echo "===== engine log (tail) ====="; tail -40 engine.log || true
+      - name: Failover profile (two nodes, kill primary mid-load)
+        run: |
+          set +e
+          python -m harness --failover failover --db-backend postgres \
+            --report-json out/load/failover-postgres.json
+          echo "failover exit: $?"
+          set -e
+      - name: Upload baseline report
+        if: always()
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
+        with:
+          name: baseline-postgres
+          path: out/load/
+          if-no-files-found: ignore
+
+  baseline-sqlserver:
+    name: baseline (sqlserver)
+    runs-on: ubuntu-latest
+    services:
+      mssql:
+        image: mcr.microsoft.com/mssql/server:2022-latest
+        env:
+          ACCEPT_EULA: "Y"
+          MSSQL_SA_PASSWORD: "Str0ng_P@ssw0rd!"
+        ports:
+          - 1433:1433
+    env:
+      MEFOR_STORE_BACKEND: sqlserver
+      MEFOR_STORE_SERVER: localhost
+      MEFOR_STORE_PORT: "1433"
+      MEFOR_STORE_DATABASE: MessageFoundry
+      MEFOR_STORE_AUTH: sql
+      MEFOR_STORE_USERNAME: sa
+      MEFOR_STORE_PASSWORD: "Str0ng_P@ssw0rd!"
+      MEFOR_STORE_POOL_SIZE: "5"
+      MEFOR_STORE_TRUST_SERVER_CERTIFICATE: "true"
+      MEFOR_ALLOW_INSECURE_TLS: "1"
+    steps:
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6
+      - name: Set up Python
+        uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6
+        with:
+          python-version: "3.13"
+      - name: Install Microsoft ODBC Driver 18 + sqlcmd
+        run: |
+          curl -fsSL https://packages.microsoft.com/keys/microsoft.asc \
+            | sudo tee /etc/apt/trusted.gpg.d/microsoft.asc > /dev/null
+          curl -fsSL "https://packages.microsoft.com/config/ubuntu/$(. /etc/os-release; echo "$VERSION_ID")/prod.list" \
+            | sudo tee /etc/apt/sources.list.d/mssql-release.list > /dev/null
+          sudo apt-get update
+          sudo ACCEPT_EULA=Y apt-get install -y msodbcsql18 mssql-tools18 unixodbc-dev
+      - name: Wait for SQL Server and create the database (RCSI on)
+        run: |
+          sqlcmd=/opt/mssql-tools18/bin/sqlcmd
+          for i in $(seq 1 40); do
+            if "$sqlcmd" -S localhost -U sa -P 'Str0ng_P@ssw0rd!' -C -Q "SELECT 1" > /dev/null 2>&1; then echo "up"; break; fi
+            echo "waiting ($i)"; sleep 2
+          done
+          "$sqlcmd" -S localhost -U sa -P 'Str0ng_P@ssw0rd!' -C \
+            -Q "IF DB_ID('MessageFoundry') IS NULL CREATE DATABASE MessageFoundry; ALTER DATABASE MessageFoundry SET READ_COMMITTED_SNAPSHOT ON WITH ROLLBACK IMMEDIATE;"
+      - name: Install project (dev + sqlserver)
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev,sqlserver]"
+      - name: Environment stamp
+        run: |
+          mkdir -p out/load
+          { echo "## sqlserver"; uname -a; python --version; git rev-parse HEAD; } | tee out/load/env-sqlserver.txt
+      - name: Serve (SQL Server) + reference rate-steps
+        env:
+          MEFOR_AUTH_ENABLED: "false"
+          MEFOR_LOAD_SINK_PORT: "2700"
+        run: |
+          set -o pipefail
+          python -m messagefoundry serve --config harness/config/load --env dev \
+            --host 127.0.0.1 --port 8765 > engine.log 2>&1 &
+          engine_pid=$!
+          for _ in $(seq 1 60); do curl -sf http://127.0.0.1:8765/health > /dev/null && break || sleep 0.5; done
+          set +e
+          python -m harness --load reference --engine http://127.0.0.1:8765 --sink-port 2700 \
+            --db-backend sqlserver --report-json out/load/reference-sqlserver.json --report-csv out/load/reference-sqlserver.csv
+          set -e
+          kill "$engine_pid" 2>/dev/null || true
+          echo "===== engine log (tail) ====="; tail -40 engine.log || true
+      - name: Failover profile (two nodes, kill primary mid-load)
+        run: |
+          set +e
+          python -m harness --failover failover --db-backend sqlserver \
+            --report-json out/load/failover-sqlserver.json
+          echo "failover exit: $?"
+          set -e
+      - name: Upload baseline report
+        if: always()
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
+        with:
+          name: baseline-sqlserver
+          path: out/load/
+          if-no-files-found: ignore