exordos-mail 0.0.2__tar.gz

exordos_mail-0.0.2/.github/workflows/build.yml

@@ -0,0 +1,125 @@
+name: build
+
+on:
+  push:
+  pull_request:
+    types: [opened]
+
+env:
+  PACKER_VERSION: "1.9.2"
+  PYTHON_VERSION: "3.12"
+  CORE_ENDPOINT_URL: http://10.20.0.2:80/api/core
+  CORE_USERNAME: "admin"
+  CORE_PASSWORD: "admin"
+  ELEMENT_NAME: mailaas
+
+jobs:
+  Build:
+    runs-on: ubuntu-24.04
+    if: ${{ github.actor != 'dependabot[bot]' }}
+    steps:
+      - name: Setup packer
+        uses: hashicorp/setup-packer@main
+        with:
+          version: ${{ env.PACKER_VERSION }}
+
+      - name: Install exordos CLI
+        run: curl -fsSL https://repo.exordos.com/install.sh | sudo sh
+
+      - name: Install hypervisor
+        run: |
+          sudo exordos compute hypervisors init
+          sudo chmod 666 /dev/kvm
+
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+
+      - name: Set up Python ${{ env.PYTHON_VERSION }}
+        uses: actions/setup-python@v6
+        with:
+          python-version: ${{ env.PYTHON_VERSION }}
+
+      - name: Install uv + tox + build
+        uses: astral-sh/setup-uv@v7
+      - run: |
+          uv tool install tox --with tox-uv
+          pip install build
+
+      - name: Build and push exordos_mail
+        timeout-minutes: 20
+        env:
+          PUSH_EXORDOS_CFG: ${{ secrets.PUSH_EXORDOS_CFG }}
+        run: |
+          set -eux
+
+          VERSION="$(exordos get-version .)"
+
+          exordos build $(pwd)
+
+          echo "$PUSH_EXORDOS_CFG" | base64 -d > exordos/exordos.push.yaml
+          exordos push -c exordos/exordos.push.yaml -t exordos_repo -f --latest
+
+          echo "MAILAAS_VERSION=${VERSION}" >> $GITHUB_ENV
+
+      - name: Configure exordos settings
+        run: |
+          exordos settings set-realm default --endpoint $CORE_ENDPOINT_URL
+          exordos settings set-context default --name default --user $CORE_USERNAME --password $CORE_PASSWORD
+
+      - name: Bootstrap exordos_core
+        run: exordos bootstrap -i latest -f -m core --admin-password $CORE_PASSWORD --cidr 10.20.0.0/22
+
+      - name: Wait for Exordos Core API
+        run: |
+          for i in {1..60}; do
+            if exordos ready_api; then
+              echo "Exordos Core API is ready"
+              break
+            fi
+            echo "Waiting for Exordos Core API... ($i/60)"
+            sleep 5
+          done
+
+      - name: Set hypervisor with overbooking
+        run: |
+          HYPER_UUID="$(exordos c h l -o json | jq -r .[0]."UUID")"
+          exordos compute hypervisors update $HYPER_UUID --cores-ratio 10.0 --ram-ratio 10.0
+
+      - name: Build + serve + install (prepare_env.py)
+        run: |
+          tox -e develop
+
+          .tox/develop/bin/python \
+            exordos_mail/tests/functional/prepare_env.py \
+            --project-dir . \
+            --output-dir /tmp/metapaas-mail-build \
+            --endpoint $CORE_ENDPOINT_URL \
+            --username $CORE_USERNAME \
+            --password "${CORE_PASSWORD}" \
+            --wait-timeout 600 \
+            2>&1 | tee /tmp/prepare_env.log
+
+          grep "^  export " /tmp/prepare_env.log | sed 's/^  export //' >> $GITHUB_ENV
+
+      - name: Wait for Mail API
+        run: |
+          CP_URL=$(grep "EXORDOS_MAIL_CP_URL" $GITHUB_ENV | cut -d= -f2)
+          for i in {1..30}; do
+            CODE=$(curl -s -o /dev/null -w "%{http_code}" "${CP_URL}/v1/")
+            if echo "$CODE" | grep -qE "200|404"; then
+              echo "MetaPaaS user-api ready (HTTP $CODE)"; exit 0
+            fi
+            echo "Waiting ($i/30) for user-api…"; sleep 10
+          done
+          exit 1
+
+      - name: Run functional tests
+        run: tox -e ${{ env.PYTHON_VERSION }}-functional
+
+      - name: Debug session on failure
+        uses: owenthereal/action-upterm@v1
+        if: failure()
+        with:
+          limit-access-to-actor: true
+          wait-timeout-minutes: 30

exordos_mail-0.0.2/.github/workflows/publish-to-pypi.yml

@@ -0,0 +1,97 @@
+name: Publish Python 🐍 distribution 📦 to PyPI
+
+on:
+  push:
+    tags:
+      - '*'
+
+jobs:
+  build:
+    name: Build distribution 📦
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v6
+      with:
+        persist-credentials: false
+    - name: Set up Python
+      uses: actions/setup-python@v6
+      with:
+        python-version: "3.12"
+    - name: Install pypa/build
+      run: >-
+        python3 -m
+        pip install
+        build
+        --user
+    - name: Build a binary wheel and a source tarball
+      run: python3 -m build
+    - name: Store the distribution packages
+      uses: actions/upload-artifact@v7
+      with:
+        name: python-package-distributions
+        path: dist/
+
+  publish-to-pypi:
+    name: >-
+      Publish Python 🐍 distribution 📦 to PyPI
+    needs:
+    - build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/exordos_mail
+    permissions:
+      id-token: write  # IMPORTANT: mandatory for trusted publishing
+
+    steps:
+    - name: Download all the dists
+      uses: actions/download-artifact@v8
+      with:
+        name: python-package-distributions
+        path: dist/
+    - name: Publish distribution 📦 to PyPI
+      uses: pypa/gh-action-pypi-publish@release/v1
+
+  github-release:
+    name: >-
+      Sign the Python 🐍 distribution 📦 with Sigstore
+      and upload them to GitHub Release
+    needs:
+    - publish-to-pypi
+    runs-on: ubuntu-latest
+
+    permissions:
+      contents: write  # IMPORTANT: mandatory for making GitHub Releases
+      id-token: write  # IMPORTANT: mandatory for sigstore
+
+    steps:
+    - name: Download all the dists
+      uses: actions/download-artifact@v8
+      with:
+        name: python-package-distributions
+        path: dist/
+    - name: Sign the dists with Sigstore
+      uses: sigstore/gh-action-sigstore-python@v3.3.0
+      with:
+        inputs: >-
+          ./dist/*.tar.gz
+          ./dist/*.whl
+    - name: Create GitHub Release
+      env:
+        GITHUB_TOKEN: ${{ github.token }}
+      run: >-
+        gh release create
+        "$GITHUB_REF_NAME"
+        --repo "$GITHUB_REPOSITORY"
+        --notes ""
+    - name: Upload artifact signatures to GitHub Release
+      env:
+        GITHUB_TOKEN: ${{ github.token }}
+      # Upload to GitHub Release using the `gh` CLI.
+      # `dist/` contains the built packages, and the
+      # sigstore-produced signatures and certificates.
+      run: >-
+        gh release upload
+        "$GITHUB_REF_NAME" dist/**
+        --repo "$GITHUB_REPOSITORY"

exordos_mail-0.0.2/.github/workflows/tests.yaml

@@ -0,0 +1,29 @@
+name: tests
+
+on:
+  push:
+  pull_request:
+    types: [opened]
+
+jobs:
+  Lint:
+    runs-on: ubuntu-24.04
+    strategy:
+      fail-fast: true
+      matrix:
+        python-version: [ "3.12" ]
+    steps:
+      - uses: actions/checkout@v6
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v6
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install requirements
+        run: sudo apt update && sudo apt install --yes libev-dev libvirt-dev
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+      - name: Install tox-uv
+        run: uv tool install tox --with tox-uv
+      - name: ruff
+        run: |
+          tox -e ruff-check

exordos_mail-0.0.2/.gitignore

@@ -0,0 +1,12 @@
+.venv/
+.tox/
+__pycache__/
+*.pyc
+*.egg-info/
+dist/
+build/
+cover/
+output/
+*.raw
+*.zst
+.pytest_cache/

exordos_mail-0.0.2/Makefile

@@ -0,0 +1,48 @@
+SHELL := bash
+SSH_KEY    ?= ~/.ssh/id_ed25519.pub
+REPOSITORY ?= http://10.20.0.1:8080/exordos-elements
+INDEX_URL  ?= http://10.20.0.1:8080/simple/
+PKG_VERSION ?=
+
+all: help
+
+help:
+	@echo "build            - build the mailaas element manifest + DP image"
+	@echo "install          - install mailaas element into Core"
+	@echo "wheel            - build Python wheel for exordos_mail"
+	@echo "publish-wheel    - copy wheel to local pip index"
+	@echo "lint             - run ruff check"
+	@echo "format           - run ruff format"
+	@echo "test             - run unit tests via tox"
+	@echo "functional       - run functional tests (needs live stand)"
+	@echo "typecheck        - run mypy"
+
+build:
+	exordos build -c exordos/exordos.yaml -i $(SSH_KEY) -f \
+		--manifest-var repository=$(REPOSITORY) \
+		--manifest-var index_url=$(INDEX_URL) \
+		$(if $(PKG_VERSION),--manifest-var pkg_version=$(PKG_VERSION),)
+
+install:
+	exordos em elements install output/manifests/mailaas.yaml
+
+wheel:
+	python -m build --wheel
+
+publish-wheel: wheel
+	cp dist/exordos_mail-*.whl /srv/exordos-local-repo/simple/
+
+lint:
+	tox -e ruff-check
+
+format:
+	tox -e ruff
+
+test:
+	tox -e py312
+
+functional:
+	tox -e py312-functional
+
+typecheck:
+	tox -e mypy

exordos_mail-0.0.2/PKG-INFO

@@ -0,0 +1,254 @@
+Metadata-Version: 2.4
+Name: exordos_mail
+Version: 0.0.2
+Summary: SMTP relay PaaS plugin for the Exordos MetaPaaS runtime (exim4)
+Author-email: Genesis Corporation <mail@gmelikov.ru>
+License: Apache-2.0
+Project-URL: homepage, https://github.com/infraguys/metapaas_mail/
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: oslo.config<10.0.0,>=3.22.2
+Requires-Dist: restalchemy<16.0.0,>=15.0.0
+Requires-Dist: gcl_iam<2.0.0,>=1.0.3
+Requires-Dist: gcl_looper<2.0.0,>=1.2.3
+Requires-Dist: gcl_sdk<4.0.0,>=3.0.5
+Requires-Dist: exordos_metapaas>=0.0.1
+Requires-Dist: passlib>=1.7.0
+Provides-Extra: dev
+Requires-Dist: tox>=4.0.0; extra == "dev"
+Requires-Dist: tox-uv; extra == "dev"
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Provides-Extra: test
+Requires-Dist: coverage>=4.0; extra == "test"
+Requires-Dist: mock<4.0.0,>=3.0.5; extra == "test"
+Requires-Dist: pytest<9.0.0,>=8.0.0; extra == "test"
+Requires-Dist: pytest-timer<2.0.0,>=1.0.0; extra == "test"
+Requires-Dist: exordos<3.0.0,>=2.0.0; extra == "test"
+Provides-Extra: ruff
+Requires-Dist: ruff; extra == "ruff"
+Provides-Extra: mypy
+Requires-Dist: mypy; extra == "mypy"
+
+# mailaas: SMTP Relay PaaS Plugin for MetaPaaS
+
+exim4 SMTP submission server packaged as a MetaPaaS plugin,
+following the same pattern as `metapaas_s3`.
+
+## Architecture
+
+```
+metapaas-cp
+└── mail plugin (exordos_paas_mail)
+    ├── CP: MailInstance + MailAccount models, REST API, migrations
+    ├── infra_builder: CoreInfraBuilder → NodeSet + Config on core
+    └── paas_builder: MailInstanceBuilder → MailInstanceNode → DP agent
+
+mailaas-dp-<uuid> (VM)
+└── exim4 (SMTP 25/465/587 — STARTTLS + auth)
+    ├── /etc/exordos_metapaas/mail.env  ← delivered by CP (MAIL_DOMAIN)
+    ├── /etc/exim4/passwd               ← managed by DP agent (lsearch auth)
+    └── exordos-universal-agent         ← MailCapabilityDriver
+```
+
+## Quick Start
+
+### Build
+
+```bash
+make build \
+  REPOSITORY=http://10.20.0.1:8080/exordos-elements \
+  INDEX_URL=http://10.20.0.1:8080/simple/
+```
+
+Produces:
+- `output/images/exordos-metapaas-mail-dp.raw.zst` (DP image)
+- `output/manifests/mailaas.yaml` (element manifest)
+
+### Install on running metapaas
+
+```bash
+make install
+```
+
+PluginReconciler on metapaas-cp installs `exordos_paas_mail` via pip and
+activates the `/v1/types/mail/` route.
+
+### Create Instance
+
+```bash
+curl -X POST http://metapaas-cp:8080/v1/types/mail/instances/ \
+  -H 'Content-Type: application/json' \
+  -H 'Authorization: Bearer <token>' \
+  -d '{
+    "name": "mail-prod",
+    "project_id": "4d657461-0000-0000-0000-000000000002",
+    "domain": "example.com",
+    "cpu": 2,
+    "ram": 2048,
+    "disk_size": 20,
+    "version": "/v1/types/mail/versions/<version-uuid>"
+  }'
+```
+
+### Create SMTP Account
+
+```bash
+# Generate SHA512-crypt hash (compatible with exim4 crypteq)
+HASH=$(openssl passwd -6 "mypassword")
+
+curl -X POST http://metapaas-cp:8080/v1/types/mail/instances/<uuid>/accounts/ \
+  -H 'Content-Type: application/json' \
+  -H 'Authorization: Bearer <token>' \
+  -d "{
+    \"username\": \"alice\",
+    \"password_hash\": \"${HASH}\",
+    \"project_id\": \"4d657461-0000-0000-0000-000000000002\",
+    \"instance\": \"/v1/types/mail/instances/<uuid>\"
+  }"
+```
+
+Within seconds the DP agent writes the account to `/etc/exim4/passwd` and
+reloads exim4. The user can then authenticate via SMTP AUTH (PLAIN/LOGIN over
+STARTTLS on port 587 or SMTPS on port 465).
+
+Hashes stored with a Dovecot `{SHA512-CRYPT}` scheme prefix are accepted — the
+driver strips the prefix before writing to exim4's passwd file.
+
+### Configure DNS
+
+For mail to be accepted by other servers you must publish a few DNS records for
+your domain (referred to below as `$1`, e.g. `example.com`).
+
+- **DKIM** — the key is generated on the node by the configure script. Once the
+  instance is `ACTIVE`, read it from the API:
+
+  ```bash
+  curl -s http://metapaas-cp:8080/v1/types/mail/instances/<uuid> \
+    -H 'Authorization: Bearer <token>' | jq -r '{dkim_selector, dkim_public_key}'
+  ```
+
+  Publish it as a `TXT` record at `<dkim_selector>._domainkey.$1`
+  (default selector: `platform`), with the `dkim_public_key` value as data.
+  The raw record is also on the node at `/etc/exim4/dkim/platform.txt`.
+- **SPF** — name: `@` (the domain itself), type: `TXT`, TTL: 3600,
+  data: `"v=spf1 ip4:YOUR_SERVER_IP/32 a mx ~all"`
+- **DMARC** — name: `_dmarc`, type: `TXT`, TTL: 3600,
+  data: `"v=DMARC1; p=none; pct=100; adkim=s; aspf=s"`
+- **PTR** — set the reverse record for your server IP to `$1`
+- **MX** — ensure an `MX` record exists (e.g. name: `@`, type: `MX`, data: `$1`)
+
+## API Endpoints
+
+| Method | Path | Description |
+|--------|------|-------------|
+| POST   | `/v1/types/mail/instances/` | Create mail server |
+| GET    | `/v1/types/mail/instances/` | List instances |
+| GET    | `/v1/types/mail/instances/<uuid>` | Get instance |
+| PATCH  | `/v1/types/mail/instances/<uuid>` | Update (cpu/ram/disk_size) |
+| DELETE | `/v1/types/mail/instances/<uuid>` | Delete |
+| GET    | `/v1/types/mail/versions/` | List DP image versions |
+| POST   | `/v1/types/mail/instances/<uuid>/accounts/` | Create account |
+| GET    | `/v1/types/mail/instances/<uuid>/accounts/` | List accounts |
+| PATCH  | `/v1/types/mail/instances/<uuid>/accounts/<uuid>` | Update (active, password_hash) |
+| DELETE | `/v1/types/mail/instances/<uuid>/accounts/<uuid>` | Delete account |
+
+### Field permissions
+
+| Field | Create | Read | Update |
+|-------|--------|------|--------|
+| `domain` | RW | RO | RO |
+| `status` | — | RO | RO |
+| `ipsv4` | — | RO | RO |
+| `dkim_public_key` | — | RO | RO |
+| `dkim_selector` | — | RO | RO |
+| `password_hash` | RW | hidden | RW |
+| `username` | RW | RO | RO |
+| `active` | RW | RW | RW |
+
+## Repository Layout
+
+```
+.
+├── exordos_paas_mail/
+│   ├── constants.py          # MAIL_ENV_FILE, EXIM4_PASSWD_FILE paths
+│   ├── models.py             # MailVersion, MailInstance, MailAccount (restalchemy)
+│   ├── controllers.py        # REST controllers (gcl_iam policy-based)
+│   ├── routes.py             # Route tree (instances/accounts, versions)
+│   ├── definition.py         # MailDefinition (PaaSDefinition contract)
+│   ├── infra_models.py       # MailInstance + infra (NodeSet + Config)
+│   ├── infra_builder.py      # CoreInfraBuilder (creates VMs + delivers mail.env)
+│   ├── paas_models.py        # MailInstanceNode (target resource for DP agent)
+│   ├── paas_builder.py       # MailInstanceBuilder (maps accounts → DP payload)
+│   ├── driver.py             # MailCapabilityDriver: writes /etc/exim4/passwd
+│   ├── utils.py              # remove_nested_dm helper
+│   ├── migrations/
+│   │   ├── 0000-init-mail.py # Creates mail_versions, mail_instances, mail_accounts
+│   │   └── 0001-drop-root-password.py
+│   └── tests/
+│       ├── unit/             # Unit tests (models, driver)
+│       └── functional/       # E2E tests (prepare_env.py + SMTP auth tests)
+├── exordos/
+│   ├── exordos.yaml          # Build config (deps + elements + DP image)
+│   ├── images/
+│   │   ├── dp_install.sh     # Packer: install exim4 + configure script + agent
+│   │   └── dp_bootstrap.sh   # First-boot: persistent disk + start configure service
+│   └── manifests/
+│       ├── mailaas.yaml.j2  # Element manifest: type reg + IAM + DP version
+│       └── example_mail.yaml.j2  # Example consumer element
+├── etc/
+│   ├── systemd/
+│   │   ├── exordos-metapaas-mail-configure.service  # Configures exim4 from mail.env
+│   │   └── exordos-metapaas-mail-agent.service      # Universal agent (MailCapabilityDriver)
+│   └── exordos_metapaas/
+│       ├── logging.yaml
+│       └── metapaas_mail_agent.conf
+├── .github/workflows/
+│   ├── tests.yaml            # Lint (ruff) on every push
+│   └── func_tests.yaml       # Full e2e: bootstrap core + deploy + SMTP tests
+├── pyproject.toml
+├── tox.ini
+└── Makefile
+```
+
+## Development
+
+```bash
+make test          # Unit tests via tox
+make lint          # ruff check
+make format        # ruff format
+make typecheck     # mypy
+make functional    # E2E tests (needs live stand)
+```
+
+### Running functional tests manually
+
+```bash
+python exordos_paas_mail/tests/functional/prepare_env.py \
+  --metapaas-dir ../exordos_metapaas \
+  --project-dir . \
+  --output-dir /tmp/mail-build \
+  --endpoint http://10.20.0.2:11010 \
+  --username admin --password <pass>
+
+# Use env vars printed by prepare_env.py, then:
+tox -e py312-functional
+```
+
+## Key differences from metapaas_s3
+
+| Aspect | s3aas | mailaas |
+|--------|-------|---------|
+| DP software | RustFS | exim4 (SMTP relay) |
+| Instance children | Bucket, Policy, User, AccessKey | Account |
+| Replicas | 1–16 | Always 1 |
+| Config delivered | `rustfs.env` | `mail.env` (domain only) |
+| DP auth state | S3 access keys | `/etc/exim4/passwd` (SHA512-crypt) |
+| On-change | `systemctl restart rustfs` | `systemctl restart mail-configure` |
+| DP agent state file | `s3_meta.json` | `mail_meta.json` |
+| uuid5 name | `s3aas` | `mailaas` |
+
+## References
+
+- MetaPaaS design: `../exordos_metapaas/DESIGN.md`
+- How to build new PaaS: `../exordos_s3/HOW_TO_BUILD_NEW_PAAS.md`
+- Working reference: `../exordos_s3/`