Developer Guide

Source Repositories

The Rexec ecosystem is spread across four GitHub repositories. Each has a distinct responsibility:

Repository Map

This meta-repo (sci-ndp/rexec) contains documentation, helm charts, and user notebooks. It does not contain source code for any of the runtime components.

sci-ndp/rexec/              # this repo — docs, helm, examples
├── helm/
│   └── rexec/              # umbrella Helm chart
│       ├── Chart.yaml
│       ├── values.yaml.template
│       ├── scidx-rexec-broker/
│       ├── scidx-rexec-server-deploy-api/
│       └── ndp-ep-api/
├── user/
│   ├── ndp-ep-rexec.ipynb  # NDP EP + rexec example
│   └── direct-rexec-lib.ipynb
├── reference/
│   ├── svg/                # architecture diagrams
│   └── legacy-doc/         # manual deploy docs
└── docs/                   # this GitHub Pages site

Dev Prerequisites

• Python 3.9+ (3.11 recommended)
• git
• A ZeroMQ-capable environment (standard on macOS/Linux)
• Docker + Docker Compose (for broker / deploy API local runs)
• Access to a Kubernetes cluster (optional, for end-to-end testing)

Path A — Develop the NDP EP Library (editable)

Use this path when you're working on ndp-ep-py. The scidx-rexec library is pulled in from PyPI as a normal dependency.

git clone https://github.com/sci-ndp/ndp-ep-py.git
cd ndp-ep-py

pip install -e ".[rexec]"

Path B — Develop the Rexec Client Library (editable)

Use this path when you're working on SciDx-rexec itself.

git clone https://github.com/sci-ndp/SciDx-rexec.git
cd SciDx-rexec

pip install -e .

# In a separate directory:
git clone https://github.com/sci-ndp/ndp-ep-py.git
cd ndp-ep-py
pip install -e ".[rexec]"
# pip will use your local editable scidx-rexec since it's already installed

Testing scidx-rexec Directly

When contributing to or debugging SciDx-rexec, you can bypass the NDP Endpoint layer entirely and drive the library directly with remote_func. This is the fastest way to iterate on the client library in isolation.

from rexec.client_api import remote_func

token = "<user-token>"

# Point directly at the broker
remote_func().set_remote_addr("<example.broker.addr>")
remote_func().set_remote_port("5559")
remote_func().set_exec_token(token)

# Point at the deploy API to auto-provision a server pod
remote_func().set_api_url("http://example.deploy.api.addr/rexec/spawn")
remote_func().set_environment("input_requirements.txt", token)

@remote_func
def my_fn():
    import platform
    return platform.node()

result = my_fn()
print(result)

ZeroMQ Protocol

Rexec uses a ROUTER–DEALER ZeroMQ pattern at the broker:

Client (DEALER) ──→ Broker frontend (ROUTER)
                         │
                    [routing table]
                         │
Broker backend (ROUTER) ──→ Server Pod (DEALER)

• Clients connect to the external NodePort (30001) as DEALER sockets
• Server pods connect to the internal ClusterIP (5560) as DEALER sockets
• The broker is stateless — it forwards frames based on identity routing
• Authentication is validated at the connection handshake via token

Server Pod Lifecycle

Authentication Flow

Client                   NDP EP API              AUTH_API_URL
  │                          │                         │
  │── GET /api/rexec/spawn ──▶│                         │
  │   Authorization: Bearer  │── GET <AUTH_API_URL> ──▶│
  │                          │   Authorization: Bearer  │
  │                          │◀── {username, groups} ───│
  │                          │                         │
  │      (if ACL enabled)    │
  │                          │── check groups ──▶ [allow/deny]
  │                          │
  │◀── {broker_url, ...} ────│
  │                          │
  │── ZMQ DEALER connect ──▶ [Broker]
  │   token in handshake     │── validate token ──▶ AUTH_API_URL

Contributing Guidelines

Client Library and Server Repos

For scidx-rexec (client library) and the rexec server repo, follow the standard PR process — open a pull request against main, and a rexec admin will review and merge accordingly. PyPI releases for the client library are managed exclusively by the rexec admin team; contributors do not need to handle publishing.

Docker Image CI: Broker and Server Deploy API

The broker and server-deploy-api repos each have a GitHub Actions workflow that fires on every merge to main. It builds the Docker image and pushes it to Docker Hub under the latest tag automatically.

Commit Style

Follow Conventional Commits:

feat: add async job dispatch to rexec client
fix: handle ZMQ timeout on broker disconnect
docs: add deploy API auth flow diagram
chore: bump scidx-rexec dependency to 0.2.0

Release Process (Helm Chart)

The Helm chart is released automatically via the release-charts.yaml GitHub Actions workflow using helm/chart-releaser-action.

# helm/rexec/Chart.yaml
version: 0.1.2    # ← increment this
appVersion: "0.1.0"

git add helm/rexec/Chart.yaml
git commit -m "chore: bump chart to 0.1.2"
git push origin main

Local Helm Chart Development

# Update subcharts
helm dependency update ./helm/rexec

# Lint
helm lint ./helm/rexec

# Template render (dry-run)
helm template rexec ./helm/rexec \
  -f ./helm/rexec/values.yaml \
  --debug

# Install to a local cluster (e.g., kind or minikube)
helm upgrade --install rexec ./helm/rexec \
  -f ./helm/rexec/values.yaml \
  -n rexec --create-namespace

kind create cluster --name rexec-dev
kubectl config use-context kind-rexec-dev
helm upgrade --install rexec ./helm/rexec -f ./helm/rexec/values.yaml -n rexec --create-namespace