REE Service

The ree_service component integrates the RDMC platform with the external Reusable Execution Environment (REE) service. It provides the Execution Environment step of the creation wizard (the REE Workbench) and acts as an authenticated proxy between the user’s browser and the REE REST API.

Architecture

The component never talks to Docker or build infrastructure itself. All heavy lifting (building, exporting, validating execution environments) happens in the external REE service (REE_URL, default https://ree.create.nfdixcs.org). ree_service is responsible for:

  • rendering the REE Workbench page (wizard step 2),

  • forwarding JSON/file requests from the browser to the REE API (adding OAuth credentials on the way),

  • persisting the link between a container and its REE,

  • saving REE job results back into the container as regular resources.

        flowchart LR
    Browser["Browser (ree_workbench.js)"] -->|JSON/file requests| App["ree_service views"]
    App -->|"OAuth or plain HTTP"| REE["External REE service /api/v3/"]
    App -->|ContainerREE, Upload records| DB[("RDMC database")]
    App -->|job artifacts| Media["MEDIA_ROOT / container files"]
    

Component Layout

ree_service/
├── apps.py                     # AppConfig (ReeServiceConfig)
├── models.py                   # ContainerREE, UnboundREE, BoundREE, forms
├── urls.py                     # Routes (included from rdmc.urls without prefix)
├── migrations/
├── views/
│   ├── ree.py                  # Proxy endpoints: components, jobs, logs, artifacts
│   └── ree_workbench.py        # Workbench page + container-side JSON endpoints
├── templates/
│   ├── ree_workbench.html      # The Execution Environment wizard step
│   └── ree_definition.html     # Legacy definition page
└── static/ree_service/
    ├── css/styles_ree_workbench.css
    └── js/ree_workbench.js     # (+ ree_common.js, ree_components.js, ree_definition.js)

Models

Model

Purpose

ContainerREE

One-to-one link between a container (rdmc.ContainerDetail) and its REE on the external service (ree_identifier, ree_name). This is what makes the Workbench reopen the same REE when the user returns to the step.

UnboundREE

Legacy flow: an REE whose definition was started during container creation but that has not yet been added (bound) to the container.

BoundREE

Legacy flow: an REE created from an upload and added to a container.

Settings & Feature Flag

Setting / flag

Meaning

REE_URL

Base URL of the external REE service. A scheme is added automatically if missing (get_ree_base_url()).

REE_AUTH_ENABLED

When true (default), all REE calls go through the Authlib OAuth client academic_cloud (the user’s AcademicCloud token is used). When false (local REE without authentication), the drop-in UnauthenticatedREEClient sends plain HTTP requests instead. get_ree_client() selects the right client.

REE_ENABLED (feature flag, FEATURE_REE_ENABLED environment variable)

Checked via rdmc.features.is_active('REE_ENABLED') at the start of every endpoint. When inactive, endpoints return 403 and the Workbench shows a “feature disabled” notice while still allowing the user to continue the wizard.

The REE Workbench

The Workbench (templates/ree_workbench.html + static/ree_service/js/ree_workbench.js) is the wizard’s Execution Environment step. Its server-side state is minimal: the template receives the container’s ree_id and ree_name (from ContainerREE) and the artifact list; everything else is loaded by the JavaScript through the JSON endpoints below.

The user flow it implements:

  1. Create an REE by name (handle_create_ree_post → POST /api/v3/rees on the external service; the returned identifier is persisted in ContainerREE).

  2. Fill the three component slots — repository, runtime, and sbom — either by picking an existing container resource or by uploading a file from the user’s device. Uploaded component files are also stored as container uploads (resource type REE, artifact_location="upload_from_device").

  3. Run jobs — export, build, and validate — and watch their state in the Pipeline panel (job list, log download, artifact download).

  4. Save job artifacts back into the container: the result file is written into the selected artifact folder and registered as a regular upload with the internal resource type ree_export, ree_build, or ree_validation, so it appears in the Artifact Initialization step and ends up in the sealed container.

Endpoints

All routes live in ree_service/urls.py and are included from rdmc.urls without a prefix. Two groups exist:

Proxy endpoints (views/ree.py) — thin authenticated proxies to the external REE API (/api/v3/…); responses are passed through unchanged, and each interaction is logged:

Route

Purpose

POST ree/update/

Rename an REE / update its metadata.

GET/PATCH/DELETE rees/<ree_id>/components/<type>/

Read, set, or clear one component slot.

POST rees/<ree_id>/jobs/<job_type>/

Start a job (export | build | validate).

GET rees/<ree_id>/jobs/

List the jobs of an REE.

GET jobs/<job_id>/ / …/log/ / …/artifact/

Job details, log file, and result artifact (streamed).

POST jobs/<job_id>/artifact/save/

Fetch the job artifact and persist it in the container (save_ree_artifact_to_container).

GET components/<type>/extensions/

Allowed file extensions per component slot (enforced by the REE service — its error messages are surfaced to the user as-is).

Workbench endpoints (views/ree_workbench.py) — container-side JSON endpoints that never leave the application process (except readiness/jobs, which aggregate REE API data via the ReeApi wrapper):

Route

Purpose

GET ree-workbench/container/artifacts/

Artifact/folder tree of the active container for the resource picker.

GET ree-workbench/container/resources/

File resources of one artifact (with extension filtering); includes loose uploads, folder-upload rows, and on-disk files.

GET ree-workbench/container/saved/

REE job artifacts already saved into the container.

POST ree-workbench/container/saved/<upload_id>/remove/

Remove a saved job artifact (file + upload record).

GET ree-workbench/<ree_id>/components/

Current state of the three component slots.

GET ree-workbench/<ree_id>/readiness/

Aggregated readiness (which slots are filled, which jobs may start).

GET ree-workbench/<ree_id>/jobs/

Jobs with normalized state for the Pipeline panel.

POST ree-workbench/<ree_id>/components/<type>/pick/

Fill a slot from an existing container resource (file is streamed to the REE service).

POST ree-workbench/<ree_id>/components/<type>/upload/

Fill a slot with a file uploaded from the user’s device.

Conventions & Pitfalls

  • Guards first: every endpoint checks is_active('REE_ENABLED') and the HTTP method (see feature_guard) before doing anything.

  • Session container: Workbench endpoints resolve the active container from request.session["container_id"]; requests without an active container return 400.

  • Error pass-through: REE API errors are not rephrased — the message from the external service is extracted (extract_api_error) and shown to the user, because validation rules (e.g., allowed file types) are REE business logic.

  • Logging: all proxy interactions are logged via log_ree_api_interaction so support can trace REE API traffic per user.

  • Saved job artifacts are regular uploads. Anything the user saves from a job goes through Upload.create_with(...) with the internal types ree_export, ree_build, and ree_validation; stale duplicates are removed first (remove_stale_uploads).

  • Timeouts: standard calls use 10–30 s; artifact downloads stream with a 120 s timeout; streaming a component file into a slot uses 300 s.