Inflow.aiDocs

Optional technical reference. This material is for developers, integration specialists and platform administrators. For the consultant lesson, read the practical guide.

Current customer-plugin lifecycle. A customer or third-party plugin that passes the upload checks becomes active as the upload completes; there is no separate approval step. Compare the publisher's archive fingerprint before uploading trusted executable code. Packages left pending by an older Inflow version require an administrator to enable them after inspecting their details. External providers remain off until configured. See the current operator procedure for the UI, legacy-pending path, provider behavior and audit details. The preserved material below records an earlier source baseline; use this lifecycle note and the linked operator procedure for current behavior.

Preserved from source baseline d4587c7c0e073e58c2d430342f65ac55dd701bf4; source/static examples retain their stated scope. They are not new runtime verification or required consultant setup steps.

Expression Function Plugin Runner

Know who owns each execution boundary

Plugin Java is executable code. Review/approval and versioned artifact custody establish trust; PF4J/class-loader separation is not a hostile-code sandbox. The reference filesystem sidecar adds resource/process/filesystem containment, bounded IPC and an isolated invocation identity, but these controls do not make a malicious publisher trusted or its result authoritative business data.

The API composes function metadata and native host declarations, while executable customer/bundled function classes belong to the admitted runner path. The supervisor controls invocation setup/teardown and never loads the plugin classes itself. Host-bound people/system declarations retain their own compiled native checks; no customer plugin may gain those capabilities by sending a claimed workspace in its arguments.

Lifecycle fact What it means
Uploaded/staged Artifact inspection and discovered contract available for administrator review.
Approve and enable Explicit trusted administrator acceptance of the exact discovered version/fingerprint.
Enabled locally Registry/admission of the desired artifact on this node; verify actual running deployment where needed.
Invocation result Bounded untrusted return data; not independent proof of business authorization or external effect.
Timeout/cleanup failure Preserve safe failure and resource/custody state; never relabel an uncertain result success.
Bundled pack Exact platform-distribution artifact with a separate admission lifecycle.

Prepare only an owned, authorized extension environment. Follow plugin developer guide for packaging and first-party functions for descriptor choices. The cases below explain administration and diagnosis without starting services, disabling verification or resuming any held runtime.

Worked examples

Example DATA-RUNNER-01 — Trace an admitted bundled function to the correct execution owner

Scenario and inputs. Nadia wants to understand why a calendar expression appears automatically while a customer function requires approval. The application distribution includes its exact first-party artifacts; the customer plugin inventory is not a list of every function that exists in the platform.

Procedure. 1. Inspect the enabled function’s actual provider, pack/version, stable key and argument-only/host-bound classification. 2. For an executable bundled function, trace the current distribution’s artifact identity and startup admission to the runner path. 3. For a declaration-only native operation, inspect the compiled host binding and its own authorization rather than looking for a customer JAR invocation. 4. Compare the function’s expected descriptor with the running environment only through an authorized read path. 5. Keep customer administration separate from the release process that replaces bundled artifacts.

Expected result. The reader can explain why a bundled function may be discoverable without a customer approval row. The distinction preserves trusted provenance and avoids falsely claiming that all declarations execute external Java or that all function results are locally pure.

Failure and recovery. A missing bundled function is a distribution/admission or descriptor problem to be reconciled by its owner. Do not upload an unrelated lookalike into the customer inventory, replace the embedded pack in place or grant a plugin a host capability merely because the visible function name matches.

Sources. PluginRunnerSupervisorMain.java, README.md.

Example DATA-RUNNER-02 — Approve the exact customer artifact after inspecting its contract

Scenario and inputs. An authorized global administrator has an organization-approved teaching plugin artifact from its actual owner. The administrator may stage and review that version but must not assume an uploaded JAR is already safe or enabled. This example supplies no binary, credentials or permission to inspect another team’s private artifact.

Procedure. 1. Use Authorization → Expression plugins → Upload for review for the admitted JAR/ZIP. 2. Inspect validation findings, publisher, version, read-only fingerprint and all discovered function signatures. 3. Check the organization’s approval/source-custody requirements before choosing Approve and enable. 4. The native POST /api/admin/plugins/{id}/approve operation calls approveAndEnable for that exact staged identity; read back its state and catalog rather than inventing a second approval payload. 5. Retain the actual audit/history and version evidence without copying configuration or secrets into it.

Expected result. The exact approved contract and artifact become eligible through the normal lifecycle. Upload by itself is not approval, and a checksum entered by a client is not a substitute for the server’s discovered fingerprint and artifact checks.

Failure and recovery. A changed artifact/manifest or discovered contract invalidates the original review. Re-stage/review the actual owner-supplied version under policy instead of editing the stored bytes, typing an allowlisted checksum into a form or approving a same-named different JAR. Denied users should never see these administration actions.

Sources. AdminPluginController.java, AdminPluginController.java.

Example DATA-RUNNER-03 — Interpret timeout and cleanup refusal before retrying

Scenario and inputs. A permitted expression invocation fails under the reference runner’s execution deadline or cleanup proof. The operator sees a safe error code but must not assume an untrusted plugin’s own exception text or partial return data is valid business output. The sidecar and invocation identity belong to an explicitly admitted runtime lane.

Procedure. 1. Preserve the exact invocation/caller/artifact identity and safe error. 2. Distinguish capacity, timeout, memory-limit, runner-unavailable and sandbox-cleanup failures using the documented codes. 3. Read the administrator’s allowed runner status and heartbeat verdict rather than searching shared IPC or another invocation’s files. 4. For ordinary argument errors, correct the input/working set; for cleanup failure, retain quarantine/unhealthy state and ask the authorized runtime owner to establish exact teardown/replacement. 5. Reattempt only when the native operation’s own retry/uncertainty policy permits it.

Expected result. A successful result is released only after the supervisor proves the required process/filesystem cleanup. A cleanup failure discards the plugin result and keeps the affected identity/readiness unsafe rather than allowing a potentially cross-invocation response.

Failure and recovery. Never add network/capabilities, disable no-new-privileges, read another identity’s artifact or relax resource limits to hide a failure. Do not replay a potentially effectful host operation simply because a UI timed out; host effects have their own native intent/reconciliation path and are not the same as a pure argument-only function.

Sources. PluginRunnerSupervisorMain.java, InvocationSandbox.java.

Example DATA-RUNNER-04 — Retire a stale plugin kill-switch setting safely

Scenario and inputs. An authorized operator upgrades a server whose canonical configuration still carries the former dynamic-plugin kill switch. That setting was removed by owner decision (SCRUM-5122, 2026-11-12): uploaded plugins now follow only their own enabled, disabled or uninstalled state, and bundled artifacts keep their own admission path. The fragment is a relevant excerpt, not a complete production deployment recipe or permission to restart a shared API.

Procedure. 1. Read the actual canonical feature file/path for the current deployment. 2. Before the upgrade, review the installed customer plugins on Authorization → Plugins: any plugin that must not serve after the upgrade is Disabled or Uninstalled first, because a stale true no longer stops it. 3. Verify the filesystem runner is healthy. 4. Apply the upgrade and restart under the owner’s authority, preserving existing data/source/resource/retention holds. 5. Confirm the startup log line below, then delete the stale line from the configuration when convenient.

plugins.expression-functions.security.strict=true
# Retired by SCRUM-5122; ignored whatever its value. Safe to delete.
plugins.expression-functions.security.kill-switch=true

Expected result. The server starts normally and logs one retiredSettingIgnored key=plugins.expression-functions.security.kill-switch reason=REMOVED_BY_OWNER_DECISION ticket=SCRUM-5122 line; the value is not logged. Plugins serve by their own state. The key is not a feature flag any more, so the Feature Flags API refuses to set it (UNKNOWN_FLAG). Strict verification is unaffected.

Failure and recovery. To stop a plugin, use Disable or Uninstall (no restart: catalogs and assets stop on every node at commit; other nodes withdraw functions at their next reconciliation, by default within 5 s); there is no server-wide switch. Never use strict=false or process mode for untrusted production code, and do not turn an unavailable verification boundary into a claimed successful rollout.

Sources. FeatureFlagCatalog.java, FeatureConfiguration.java.

Detailed reference

This manual describes the production execution boundary for bundled Inflow and administrator-approved expression function plugins.

Trust Model

Uploaded Java is executable code. Inflow requires global administrator access to upload, review, approve, enable, disable, or delete a plugin. PF4J provides extension discovery and class-loader separation; it is not a security sandbox.

The API JVM never loads plugin classes. It delegates discovery and invocation to the plugin-runner sidecar, which starts a disposable child JVM for each request.

The eight Inflow-maintained function packs (seven executable packs plus the declaration-only inflow-functions-people pack, performed by the host) are embedded in the versioned Inflow application distribution. At startup Inflow extracts those exact classpath artifacts into the content-addressed runner volume, verifies their archive and manifest identities, requires the Inflow.ai provider, and registers them automatically. They are standard platform functionality: they do not create administrator approval records, do not appear in the customer-plugin administration inventory, and cannot be disabled or removed through the dynamic plugin lifecycle API.

Archive checksums and manifest/runtime admission are not distribution-signing certification. Host-performed declaration-only functions and system capability operations use the compiled host binding/dispatcher, not an executable customer plugin invocation. Their native authorization and effect contracts still apply.

Customer And Third-Party Administration Flow

  1. Select Upload for review and choose a JAR or ZIP.
  2. Inflow validates size, archive paths, manifest schema, identity consistency, and the discovered function catalog.
  3. Review the publisher, version, read-only fingerprint, and complete function signatures.
  4. Select Approve and enable.

Every upload, approval, enable, disable and uninstall is recorded in the audit trail with the actor, the plugin version, the state change and the fingerprint. Select History on a plugin's row to review those events, newest first. History is shown only to an administrator who may read the platform-wide audit trail (AUDIT_VIEW with WORKSPACE_MANAGE); it shows identifiers only, never plugin configuration.

The administrator does not calculate or enter a checksum. Optional deployment allowlists are configured by operators, outside this workflow.

This flow applies only to additional customer or third-party plugins. Client administrators do not upload or approve the Inflow-maintained packs. Updating Inflow replaces those bundled artifacts as part of the normal platform release.

Required Production Controls

The reference plugin-runner container enforces:

  • no network access;
  • a private root-owned IPC queue that plugin children cannot read, modify, or use to forge another invocation's response;
  • every child execution under a dedicated unprivileged UID and GID, with no effective, permitted, inheritable, or ambient capabilities and no-new-privileges;
  • a root-owned, per-invocation artifact snapshot readable by only that invocation's group; children cannot enumerate the approved artifact store or another invocation's snapshot;
  • read-only root filesystem;
  • read-only content-addressed artifact volume;
  • dropped Linux capabilities and no-new-privileges;
  • CPU, memory, PID, request-size, response-size, concurrency, queue, and execution-time bounds;
  • a 5 MiB child file-size ceiling, sufficient for every approved compressed plugin artifact and the framed response protocol;
  • per-identity process and virtual-address-space limits plus aggregate container PID and memory limits;
  • identity-wide process termination after success, failure, cancellation, or timeout, including detached descendants;
  • a stable PLUGIN_MEMORY_LIMIT_EXCEEDED failure for HotSpot out-of-memory exit 3 and container OOM/SIGKILL exit 137; other abnormal exits remain runner-unavailable failures;
  • one invocation at a time per sidecar, preventing loopback communication between concurrent plugins; throughput scales with independent API-plus-sidecar replicas;
  • a private per-invocation temporary directory; shared container /tmp is root-only;
  • a bounded invocation filesystem inode/entry budget and streaming cleanup that never materializes an attacker-controlled tree in supervisor memory;
  • identity quarantine, a safe failed invocation response, and a failed health check when complete cleanup cannot be proven;
  • safe error codes without plugin exception text.

The shared IPC volume contains bounded JSON request and response files published with atomic moves. Artifact references are checksum-derived basenames, never caller-supplied paths. Plugin input travels over a private pipe; output is written to a bounded, per-invocation protocol file that the child can write but cannot read, replace, or use to reach shared IPC. This prevents one invocation from forging another invocation's response; it does not authenticate the current plugin's own return value, which is untrusted application data. A successful response is published only after the supervisor has drained every process owned by the invocation identity and removed its private artifact snapshot. If either proof fails, the plugin result is discarded and replaced by PLUGIN_SANDBOX_CLEANUP_FAILED; the identity remains quarantined and readiness remains down until the sidecar is replaced or external teardown proves the exact sandbox has been removed.

The supervisor retains only SETUID, SETGID, and KILL so it can drop each child to a separate plugin identity and remove every process left under that identity after completion or timeout. It does not load plugin bytecode. The sidecar health check validates heartbeat freshness rather than file existence, and shutdown removes the heartbeat immediately. Do not add filesystem, network, or administrative capabilities to this container.

RLIMIT_NPROC is scoped to the real host UID. Every production sidecar replica must therefore run in its own Linux user namespace so container UID 10002 maps to a replica-unique host UID. A deployment without user-namespace isolation is not certified for horizontal plugin-runner scaling. Keep one invocation per sidecar and scale API-plus-sidecar pairs, not a shared runner container.

Configuration

Production mode is the default:

plugins.expression-functions.runner.mode=filesystem
plugins.expression-functions.runner.ipc-directory=run/plugin-runner
plugins.expression-functions.runner.timeout-ms=2000
plugins.expression-functions.runner.max-concurrency=1
plugins.expression-functions.security.strict=true

security.strict=true is mandatory outside explicit development mode. There is no global plugin kill switch: plugins.expression-functions.security.kill-switch was removed by owner decision (SCRUM-5122) and is ignored, with one startup log line, if a configuration still names it. Uploaded plugins serve according to their own enabled, disabled or uninstalled state; per-plugin Disable and Uninstall are the stop controls. The optional security.approved-checksums property is an operator-managed deployment allowlist, not an administrator upload field.

The trusted local fallback must be selected explicitly:

plugins.expression-functions.runner.mode=process
plugins.expression-functions.security.strict=false

Set these values in the canonical conf/custom_config.properties. Relaxed verification also requires canonical inflow.development-mode=true; old feature-value environment overrides are retired. These settings require a restart. API/MCP edits use the same file and retain global administrator authority. See Feature switches. Process mode is unsafe for untrusted plugins, including in development. Use it only for trusted, locally built developer plugins. Never use process mode or disabled strict verification as a production isolation boundary because the child JVM inherits the API container's filesystem, environment, and network access, and host process cleanup cannot provide the sidecar's identity-based containment guarantees.

Failure And Recovery

  • PLUGIN_CAPACITY_UNAVAILABLE: retry after load decreases.
  • PLUGIN_EXECUTION_TIMEOUT: inspect or disable the plugin; its process tree was terminated.
  • PLUGIN_EXECUTION_CANCELLED: the caller cancelled the invocation or the runner shut down; its process tree was terminated.
  • PLUGIN_SANDBOX_CLEANUP_FAILED: the plugin result was discarded because process or filesystem cleanup could not be proven. The sidecar is deliberately unhealthy; replace it before retrying.
  • PLUGIN_MEMORY_LIMIT_EXCEEDED: the invocation crossed its JVM or container memory boundary. Reduce the function's working set or split the operation.
  • PLUGIN_RUNNER_UNAVAILABLE: verify the runner container and shared IPC volume.

Plugin administrators see the runner's health on Authorization > Expression plugins (SCRUM-740), without actuator access. GET /api/admin/plugins/status (administrator only, like every plugin admin call) returns runner.state = UP, DOWN or NOT_MONITORED (no filesystem runner on this node, for example runner.mode=process) and, when DOWN, runner.code = PLUGIN_RUNNER_UNAVAILABLE (no heartbeat file) or PLUGIN_RUNNER_HEARTBEAT_STALE (heartbeat older than plugins.expression-functions.runner.heartbeat-max-age-ms). Nothing else from the health check is returned: no IPC path or host name. When the runner is down the page shows "Plugin runner unavailable" with the reason; when it is up it shows "Plugin runner healthy"; when it is not monitored, or the status cannot be read, it shows nothing about the runner.

  • PLUGIN_ARTIFACT_CHANGED: disable the plugin and investigate artifact storage integrity.
  • PLUGIN_VALIDATION_CHANGED: upload and review the artifact again; its discovered contract no longer matches approval.

Lifecycle state and artifact bytes are durable in PostgreSQL. Each API node periodically reconciles its local read-only artifact cache and in-memory function registry with that shared desired state.

Try “document generation”, “integrations” or “first form”.