PerfCheckerWeb public API

This reference renders the actual Julia docstrings of PerfCheckerWeb 1.0.0 with Core from the selected source revision. The companion retains its own version. Importing the owner does not register routes or start a server.

The full API is the canonical reference. Full API also includes documented internal bindings.

PerfCheckerWeb.PerfCheckerWeb Module

Oxygen interfaces for PerfChecker: evidence routes, Studio and native test items. Load this package explicitly and use the exported PerfChecker entry points. Starting a server requires serve_suite or an explicit Oxygen server call; importing the package alone does not listen on a port.

source

PerfChecker.register_oxygen_routes! Method

register_oxygen_routes!(root::AbstractString; prefix="/perfchecker/v1",
                        allow_ingest=false, max_ingest_bytes=10*1024*1024)

Register a saved-bundle browser and evidence routes, and return the Oxygen router. root is resolved from the working directory and must exist unless allow_ingest=true, which creates it. Reading saved results does not rerun them.

With ingestion enabled, POST /ingest writes a supplied bundle under root and returns HTTP 201. Invalid input returns 400; a body larger than the positive max_ingest_bytes limit returns 413. These routes do not add authentication. Registration starts no listener and cannot enforce its bind address; use the loopback restriction in serve_suite(root; allow_ingest=true) when hosting them.

source

PerfChecker.register_oxygen_routes! Method

register_oxygen_routes!(provider::Function; prefix="/perfchecker/v1")

Register read-only capabilities, suite and run-list routes on Oxygen's current router and return the router. Each request to /suite or /runs calls provider() and serializes its suite result. Registration does not call the provider or start an HTTP listener; any effects of the provider are the caller's responsibility. Load PerfCheckerWeb before calling this method.

source

PerfChecker.register_oxygen_routes! Method

register_oxygen_routes!(bundle::RunBundle; prefix="/perfchecker/v1")

Register read-only routes for a saved bundle and return the Oxygen router. Routes expose its manifest, measurement definitions, observations, diagnostics, artifacts and derived advice, comparisons, plots and queries. They do not rerun the measured workload. Registration does not start an HTTP listener.

source

PerfChecker.register_oxygen_routes! Method

register_oxygen_routes!(catalog::ScenarioCatalog;
    prefix="/perfchecker/scenarios", project=catalog.root, catalog_path=nothing,
    advisor=nothing, reports_root=joinpath(catalog.root, "perf", "results", "investigations"))

Register the scenario investigation UI and routes, and return the Oxygen router. Create reports_root and load saved advisor settings when present. With catalog_path, requests reload that catalog file; otherwise they use catalog. project selects the investigation controller environment.

Registration starts neither a listener nor an investigation. Explicit launch requests can discover tests, measure, diagnose or use the configured advisor; accepted jobs return HTTP 202 and persist evidence under reports_root. State-changing requests use a session CSRF token, which is not user authentication. Host these controls through the loopback-only serve_suite(catalog; ...) overload.

source

PerfChecker.register_oxygen_routes! Method

register_oxygen_routes!(result::SoftwareSuiteResult; prefix="/perfchecker/v1")

Register a fixed suite result through the provider overload and return its Oxygen router. Requests serialize the saved result without rerunning its measurements. This method does not start a server.

source

PerfChecker.register_oxygen_routes! Method

register_oxygen_routes!(suite::SoftwareSuite; profile=:quick,
    prefix="/perfchecker/v1", version_provider=get_pkg_versions,
    overrides=Dict{Symbol,Any}(), executor=PerfChecker._default_suite_executor,
    reports_root=joinpath(pwd(), "perfchecker-results"), max_concurrent=1,
    authenticator=nothing, authorizer=PerfCheckerWeb._default_studio_authorizer,
    lease_seconds=300, max_agent_attempts=3, session_hours=8, secure_cookies=false)

Register the interactive Studio, suite planning, job, saved-result and agent routes, and return the Oxygen router. reports_root is made absolute and created; persisted sessions, agents and compatible jobs are restored. Restored local jobs can resume immediately, even though this function starts no HTTP listener.

version_provider, overrides and executor configure planning and execution; max_concurrent limits active local jobs. authenticator maps a bearer token to an identity or nothing; authorizer checks that identity's requested action. lease_seconds, max_agent_attempts, session_hours and secure_cookies control agent leases and browser sessions. These options belong to this suite overload, not to the read-only bundle/provider routes. Use serve_suite(suite; ...) to apply the hosted Studio's remote-control guard and start a listener.

source

PerfChecker.register_testitem_routes! Method

register_testitem_routes!(root::AbstractString; prefix="/perfchecker/items",
    project=dirname(Base.active_project()),
    reports_root=joinpath(root, "perf", "results", "testitems"))

Register existing-test-item controls on Oxygen's current router and return the router. Load PerfCheckerWeb and TestItemRunner first. root, project and reports_root are made absolute from the caller's working directory. The default for project requires an active Julia project. The route prefix must contain only letters, digits, underscores, hyphens and slashes, and start with /.

GET /items discovers eligible items without executing them; GET /state reads the current run state. POST /run accepts a JSON object with distinct, nonempty ids from that discovery. It returns HTTP 202 and runs the selected items asynchronously in project, writing reports to a fresh directory beneath reports_root. Invalid or excluded IDs return 400; an already active run returns

1. Both POST /run and POST /cancel require the UI session's

X-PerfChecker-CSRF token or return 403. Cancellation acknowledges a request, not completed worker cleanup; inspect /state for the resulting state.

Registration does not start a listener or execute a test. The CSRF token is not authentication; configure exposure separately when starting Oxygen.

using PerfChecker, PerfCheckerWeb, TestItemRunner
routes = register_testitem_routes!(pwd(); project=abspath("perf/controller"))
# Start Oxygen separately when ready to expose these controls.

source

PerfChecker.run_studio_agent Method

run_studio_agent(suite::SoftwareSuite; server, token, agent_id,
    version_provider=get_pkg_versions, executor=PerfChecker._default_suite_executor,
    poll_seconds=2, heartbeat_seconds=30, max_jobs=typemax(Int), once=false) -> Int

Poll a hosted Studio for leased jobs, validate each selected plan against the local suite, run it locally and upload its bundle or failure. server is the Studio API base URL including its route prefix, for example "https://perf.example.org/perfchecker/v1"; token is an issued bearer token authorized for agent_id. Startup probes network-isolation capabilities, and accepted jobs can create workload processes and reports. Keep the controller, suite and credentials under the caller's control. Remote connections require HTTPS; plain HTTP is accepted only for the supported loopback URL forms.

Return the number of attempted leases, including failed attempts when once=false, rather than a count of successful jobs. once=true makes one claim request: return 0 if no job is available, return 1 after a completed attempt, or rethrow an execution/reporting error. Otherwise, empty claims keep polling; max_jobs bounds attempted leases, not idle polling time. Claim-request errors propagate. poll_seconds must be nonnegative; heartbeat_seconds and max_jobs must be positive.

An InterruptException or CheckCleanupFailure always propagates, including with once=false: the agent stops before claiming another job. A cooperative interrupt lets the suite unwind its worker and allocation-trace cleanup; a cleanup failure retains its private inventories and must be investigated before restarting. These fatal exits do not upload a completed bundle or report the lease as safely finished. The controller can retry an expired lease on a later claim, subject to its attempt limit. Workloads must tolerate that replay.

Cancelling a remote job on the controller invalidates its lease/result but does not interrupt this agent's synchronous measurement. To stop that work, interrupt the agent itself once and let cleanup finish. Force-killing its process can bypass cleanup and leave workers or allocation traces behind.

Heartbeats report progress asynchronously. Each attempt signals its heartbeat task to finish but does not wait for that task before returning or polling again. Load PerfCheckerWeb to enable this method; it does not start a local HTTP server.

source

PerfChecker.serve_suite Method

serve_suite(root::AbstractString; host="127.0.0.1", port=8080, async=false,
            prefix="/perfchecker/v1", allow_ingest=false, kwargs...)

Serve a saved-bundle directory and return Oxygen's server result. Ingestion is off by default. allow_ingest=true permits writes and requires host to be 127.0.0.1, localhost or ::1; a remote host raises ArgumentError before registration. Read-only hosting adds no remote-host or authentication guard.

Additional keywords are forwarded to both directory route registration and Oxygen.serve, so they must be accepted by both APIs. To configure route-only or server-only options separately, call register_oxygen_routes!(root; ...) followed by Oxygen.serve(; ...), with an appropriate bind address.

using PerfChecker, PerfCheckerWeb
serve_suite("perf/results"; port=8080, async=true) # existing bundle directory

source

PerfChecker.serve_suite Method

serve_suite(provider::Function; host="127.0.0.1", port=8080, async=false,
            prefix="/perfchecker/v1", kwargs...)

Register a result provider's read-only routes, then return Oxygen.serve's result. prefix configures the routes; additional keywords go only to Oxygen.serve. The default call serves on loopback and blocks according to Oxygen's server lifetime; async=true requests Oxygen's asynchronous mode. This overload adds neither authentication nor a remote-host restriction. Provider requests can have the effects described by register_oxygen_routes!(provider).

source

PerfChecker.serve_suite Method

serve_suite(bundle::RunBundle; host="127.0.0.1", port=8080, async=false,
            prefix="/perfchecker/v1", kwargs...)

Register a saved bundle's read-only evidence routes, start Oxygen and return its server result. prefix goes to route registration; other keywords go only to Oxygen.serve. The default listener is loopback and async=false; this overload does not enforce loopback or install authentication. It does not rerun the bundle's measured workload.

source

PerfChecker.serve_suite Method

serve_suite(catalog::ScenarioCatalog; host="127.0.0.1", port=8080, async=false,
    prefix="/perfchecker/scenarios", project=catalog.root, catalog_path=nothing,
    advisor=nothing, reports_root=joinpath(catalog.root, "perf", "results", "investigations"))

Register the investigation routes and return Oxygen.serve's result. Only 127.0.0.1, localhost and ::1 are accepted for host; this overload has no remote-control override. Route registration creates the report directory and loads saved advisor settings, but starts no investigation. Work begins through explicit UI/API actions.

prefix, project, catalog_path, advisor and reports_root configure the routes. Only host, port and async are passed to Oxygen; this overload does not accept arbitrary server keywords. The default async=false uses Oxygen's blocking server mode. Load PerfCheckerWeb before calling it.

source

PerfChecker.serve_suite Method

serve_suite(result::SoftwareSuiteResult; host="127.0.0.1", port=8080,
            async=false, prefix="/perfchecker/v1", kwargs...)

Serve a fixed suite result through the provider overload and return Oxygen's server result. Keywords follow that overload; serving does not remeasure the result. Load PerfCheckerWeb to enable this method.

source

PerfChecker.serve_suite Method

serve_suite(suite::SoftwareSuite; host="127.0.0.1", port=8080, async=false,
            prefix="/perfchecker/v1", allow_remote_control=false,
            authenticator=nothing, kwargs...)

Register the interactive Studio and start Oxygen, returning its server result. A non-loopback host requires both allow_remote_control=true and a supplied authenticator; otherwise throw ArgumentError before registration. The caller must also arrange suitable network exposure and transport security.

Additional keywords go only to register_oxygen_routes!(suite; ...), including its job, authorization and session options. Oxygen receives only host, port and async. Registration creates/restores the workspace and can resume persisted local jobs before the listener starts. The remote-control guard applies to this overload, not to every form of serve_suite.

source

PerfChecker.studio_token_authenticator Method

studio_token_authenticator(users::AbstractDict) -> Function

Build a bearer-token verifier from SHA-256 digest keys and caller-supplied identities. The returned function hashes a token and returns the matching identity, or nothing. Digest keys are normalized to lowercase; this dictionary overload does not validate their format or the identity's roles. It does not create credentials, grant roles, start a server or change the supplied store.

using SHA, PerfChecker, PerfCheckerWeb
identity = Dict("id" => "reader", "roles" => ["viewer"])
digest = bytes2hex(sha256("example-token")) # demonstration token only
authenticate = studio_token_authenticator(Dict(digest => identity))
@assert authenticate("example-token") === identity
@assert authenticate("different-token") === nothing

source

PerfChecker.studio_token_authenticator Method

studio_token_authenticator(path::AbstractString) -> Function

Read a TOML user store once and build the digest-to-identity verifier. Each [[users]] entry requires a nonempty id, a 64-character hexadecimal token_sha256 and nonempty roles; name defaults to id, and agent_ids is optional. Missing files, missing IDs, invalid digests, empty roles or an empty store raise ArgumentError; TOML parsing errors propagate. Relative paths are resolved from the working directory. Later file changes are not watched: rebuild the verifier to load them. Plaintext tokens are not read from this file, and this function does not provision or rotate credentials.

source