Skip to content

feat: mail-parser-api service with parse endpoint, CI and release - #1

Merged
fedelemantuano merged 6 commits into
mainfrom
feat/parse-endpoint
Nov 7, 2026
Merged

fedelemantuano merged 6 commits into
mainfrom
feat/parse-endpoint

Conversation

@fedelemantuano

Copy link
Copy Markdown
Contributor

Summary

First implementation of mail-parser-api, the stateless parse service behind the spamscope.ai live parser.

  • POST /api/parse takes a raw email (Content-Type: message/rfc822, max 5 MB) and returns {"mail_parser_version", "message"}, where message is mail-parser's mail_json with payload removed from every attachment.
  • Errors: 413 oversized body (declared and streamed size), 415 other content types (Outlook .msg not supported yet for application/vnd.ms-outlook), 422 mail-parser failure, 429 rate limit, 504 parse timeout. GET /healthz for the container health check.
  • Each request runs the installed mail-parser CLI (python -m mailparser --stdin --json) in a subprocess: fixed argv, email on stdin, no shell, killed after 10 s.
  • In-memory sliding-window limiter: 10 requests / 60 s per client key (first X-Forwarded-For value or peer; IPv4 whole, IPv6 /64), max 10 000 keys with LRU eviction and purge of expired keys. No new dependency.
  • Access log with method, path, status and response size only; uvicorn's access log is off. OpenAPI/docs routes are disabled.
  • Dockerfile on python:3.13-slim, uv, non-root user app (uid 10001), one uvicorn worker with --limit-concurrency 8; verified locally with --read-only --cap-drop ALL --tmpfs /tmp.
  • Tooling copied from mailxray-backend: ruff, pyright, pre-commit (mdformat, markdownlint), Makefile, ci.yml (release label check + lint-test-build), release.yml (version bump pushed with the RELEASE_DEPLOY_KEY deploy key, multi-arch image on GHCR, GitHub release with generated notes, no assets), Dependabot for production uv dependencies and GitHub Actions.
  • Docs: README (contract, limits, local run, release process), AGENTS.md/CLAUDE.md, GLOSSARY.md, agent docs, and a needs-triage ticket for future Outlook .msg support.

Test plan

  • make pre-commit
  • make test-cov (28 tests, 100% coverage)
  • docker run --read-only --cap-drop ALL --tmpfs /tmp: /healthz, mail_test_10 (4 attachments, no payload), 415, 413

🤖 Generated with Claude Code

@fedelemantuano fedelemantuano added the minor_release New feature, backwards compatible label Nov 7, 2026
A job skipped because a needed job failed satisfies a required check, so an unlabeled PR was mergeable. Count release labels by exact line match.
Run the mail-parser child under choom and prlimit on Linux, allow two parses at once, decode the CLI JSON in place and return a clear 422 when a parse exceeds the limits. Raise uvicorn's concurrency limit so health checks pass while parses queue.
Build the linux/amd64 image without pushing in lint-test-build, so a broken lockfile or Dockerfile fails before a release tag exists. The image build installs the package, so the uv build step and its artifact are dropped. Drop the top-level .github exclude so check-yaml covers the workflows.
…onment-scoped deploy key

Queue releases in one concurrency group so quick merges cannot race on the version bump, and reject a malformed version before the arithmetic. Trigger on pull_request_target so merged fork pull requests get the deploy key and packages: write; no job checks out pull request code. Drop workflow-level permissions and grant each job only what it needs. Read RELEASE_DEPLOY_KEY from the release environment, limited to main.
…ge build

The main ruleset now holds only pull_request and required_status_checks with the deploy key bypass; the new main-protect ruleset blocks deletion and force pushes with no bypass.
@fedelemantuano
fedelemantuano merged commit bd8acb7 into main Nov 7, 2026
1 check passed
@fedelemantuano
fedelemantuano deleted the feat/parse-endpoint branch November 7, 2026 18:28

This branch was successfully deployed

1 active deployment
release — adc1bcda Deployed Nov 7, 2026 by fedelemantuano via release #1
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

minor_release New feature, backwards compatible

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant