flux_restful.library package¶

Submodules¶

flux_restful.library.csrf module¶

Cross-site request forgery protection for the web UI forms.

The web UI authenticates with HTTP Basic auth, which browsers attach to any request to the server, including ones made from other sites. Every form therefore carries a token that must match the csrftoken cookie (the double-submit pattern). Other sites cannot read or set our cookie, so they cannot produce a matching token. The JSON API uses bearer tokens, which browsers never attach automatically, so it does not need this.

async flux_restful.library.csrf.middleware(request: Request, call_next)[source]¶: Ensure every response has a csrftoken cookie and expose the token to templates.

flux_restful.library.csrf.verify(request: Request, submitted) → None[source]¶: Check a submitted token against the cookie; raise 403 if it does not match.

async flux_restful.library.csrf.verify_form(request: Request) → None[source]¶: Verify the token in a posted form.

flux_restful.library.env module¶

The environment given to jobs and launchers.

The server’s own environment must not be copied into jobs: it holds the server’s configuration and secrets (FLUX_TOKEN, FLUX_SECRET_KEY, FLUX_TOKEN_SIGNING_KEY, …) and in multi-user mode the job runs as someone else. A job only needs a small set of variables to run and to talk to Flux; the job shell provides FLUX_URI and the FLUX_JOB_* variables itself. Operators can pass more with FLUX_JOB_ENV_PASSTHROUGH (comma separated names or fnmatch patterns).

flux_restful.library.env.build_helper_environment(extra: dict[str, str] | None = None) → dict[str, str][source]¶: The environment for processes that run on the server (not inside a job) and must reach this Flux instance: the multi-user submit script, and launchers such as nextflow or snakemake that submit their own jobs. The job environment plus FLUX_URI, which the job shell would otherwise provide.

flux_restful.library.env.build_job_environment(extra: dict[str, str] | None = None, source: dict[str, str] | None = None) → dict[str, str][source]¶

The environment for a job: allowlisted server variables plus user extras.

User provided variables (from the submit request) take precedence.

flux_restful.library.env.is_allowed(name: str, patterns: Iterable[str]) → bool[source]¶

flux_restful.library.env.passthrough_patterns() → list[source]¶: Extra names or patterns from FLUX_JOB_ENV_PASSTHROUGH.

flux_restful.library.flux module¶

flux_restful.library.handle module¶

flux_restful.library.helpers module¶

flux_restful.library.helpers.get_int_arg(payload, key)[source]¶: Attempt to get (and parse) and integer argument. Fallback to None.

flux_restful.library.helpers.get_page(name)[source]¶: Get a <page>.md file from the app root.

flux_restful.library.helpers.has_boolean_arg(payload, key)[source]¶: A helper to determine if a payload has a key, and it’s in some derivation of True

flux_restful.library.helpers.read_json(filename)[source]¶

flux_restful.library.launcher module¶

flux_restful.library.launcher.launch(kwargs, workdir=None, envars=None, user=None)[source]¶: Launch a job with a known launcher

flux_restful.library.runas module¶

Run a command as another system user (multi-user mode).

Flux jobs must be signed by the user they run as: munge stamps a credential with the real uid of the calling process, so the server cannot sign on a user’s behalf. Instead, the server (running as root) becomes the user for the duration of a helper process, whose own flux python signs and submits the jobspec. The Flux instance then accepts it as a guest job and flux-imp launches it as that user.

subprocess switches the child to the user’s uid, gid and groups after fork, so no sudoers configuration is needed. Only root can switch to another user; a switch to the current uid is skipped, which is what happens in tests.

exception flux_restful.library.runas.RunAsError[source]¶

Bases: RuntimeError

The command could not be run as the user, or exited non-zero.

flux_restful.library.runas.run_as_user(command: Sequence[str], username: str, input: str | None = None, cwd: str | None = None, env: dict | None = None) → str[source]¶: Run a command as the user and return its stdout. Raises RunAsError.

flux_restful.library.runas.switch_user_kwargs(record: struct_passwd) → dict[source]¶

Keyword arguments for subprocess.run that make the child run as the user.

subprocess does the switch itself in the child after fork (setgroups, setgid, setuid, in that order), which is safe in a threaded server where preexec_fn is not. No switch is needed when we already are the user.

flux_restful.library.runas.user_environment(record: struct_passwd, extra: dict | None = None) → dict[source]¶: The environment for a helper process run as the user: the allowlisted server environment plus FLUX_URI, with the user’s own identity variables.