APPNETOS is under active development This website and its documentation are being prepared for public launch. Content and features may change.
Select Theme
Loading

Runtime Bootstrap

The third bootstrap step creates the shared runtime state, makes it accessible during early startup, and initializes environment and HTTP or process information for the current execution.

Purpose and Execution

Bootstrap\Runtime\RuntimeBootstrap runs after Error Handling Bootstrap. It loads the protected runtime classes, constructs one RuntimeState instance, registers that instance with RuntimeStateHolder, and then populates the initial state.

public function boot(ProcessInput|null $processInput = null): RuntimeState
{
    require_once APPNETOS_ROOT . '/appnetos/shared/src/Bootstrap/Runtime/RuntimeState.php';
    require_once APPNETOS_ROOT . '/appnetos/shared/src/Bootstrap/Runtime/RuntimeStateHolder.php';

    $runtimeState = new RuntimeState();
    RuntimeStateHolder::set($runtimeState);

    $this->initEnvironment($runtimeState);

    if ($processInput !== null) {
        $this->initProcess($runtimeState, $processInput);
        return $runtimeState;
    }

    $this->initHttp($runtimeState);
    return $runtimeState;
}

Initialization order matters: the holder receives the shared state before environment, process, or HTTP fields are populated. Later bootstrap components progressively update this same object. A non-null ProcessInput selects the process branch; otherwise the HTTP branch runs.

RuntimeBootstrap creates one RuntimeState, registers the same instance in RuntimeStateHolder, initializes environment and either HTTP or process values, and later bootstrap components extend the shared state.
RuntimeStateHolder keeps a reference to the same RuntimeState instance; it does not create a second state.

RuntimeState — Shared Runtime Information

Bootstrap\Runtime\RuntimeState is a final, mutable container for the current APPNETOS startup. Its constructor immediately records the startup microtime and generates a runtime identifier from 16 cryptographically secure random bytes (32 hexadecimal characters). All other fields are initialized by the responsible bootstrap layers as startup progresses.

public function __construct()
{
    $this->microtimeStart = microtime(true);
    $this->runtimeId = bin2hex(random_bytes(16));
}

Stored Runtime Information

Category Stored information Population
General Startup microtime, runtime ID, environment, secret, debug state Constructor and RuntimeBootstrap
Applications Registered applications, application slugs, active application, PHP code origin Subsequent application resolution
Contexts Context, base context, context slug Process input or subsequent context resolution
HTTP Host, host with port, port, scheme, original URI, normalized path, path segments HTTP branch of RuntimeBootstrap
Class resolution Class extensions and class mappings Subsequent bootstrap components
Security and sessions Resolved security identity and session scope Subsequent bootstrap components
Processes Process flag, executable, operation, arguments Process branch of RuntimeBootstrap

Application Identity and Code Origin

The active application identity is distinct from its PHP code origin. This is important for alias applications: an application may have its own runtime identity while referencing a separate code origin. getOrigin() returns the origin when set, otherwise the active application. Calling setApplication() clears the previously stored origin.

public function getOrigin(): string|null
{
    return $this->origin ?? $this->application;
}

RuntimeState is deliberately mutable, but its final declaration prevents inheritance-based replacement of this protected bootstrap state container.

RuntimeStateHolder — Early Global Access

Bootstrap\Runtime\RuntimeStateHolder stores a static reference to the active RuntimeState. It bridges early bootstrap components and global helpers that cannot yet use normal dependency resolution. It does not create, validate, or independently resolve runtime values.

RuntimeStateHolder::set($runtimeState);

// Later in the bootstrap sequence:
$runtimeState = RuntimeStateHolder::get();
$runtimeId = $runtimeState->getRuntimeId();

The holder references the same mutable object used by subsequent bootstrap components; it is not a snapshot, a second state container, or an independent runtime service.

HTTP Runtime Initialization

Without ProcessInput, RuntimeBootstrap marks the runtime as non-process and initializes host, scheme, and request-path information from PHP server variables.

Host and Port Resolution

  1. Use non-empty $_SERVER['HTTP_HOST'], if available.
  2. Otherwise use $_SERVER['SERVER_NAME'] and append SERVER_PORT when present and scalar.
  3. If neither provides a usable host, retain an empty host.

Host values are trimmed and lowercased. The bootstrap stores the host without port, the host with optional port, and the optional port as separate state values.

HTTP Scheme Resolution

The bootstrap checks for HTTPS indicators in the following order:

  1. HTTP_X_FORWARDED_PROTO (only the first comma-separated value)
  2. REQUEST_SCHEME
  3. HTTPS (non-empty and not off)
  4. SERVER_PORT equal to 443
  5. Fallback: http

These checks look for a positive HTTPS indicator. An earlier value of http does not necessarily prevent a later indicator from selecting https.

Request URI and Path Segments

The original REQUEST_URI is preserved. Its path component is extracted without the query string, and the directory of the active public entry script is removed from the beginning of the path when applicable. The resulting path is split into non-empty segments.

SCRIPT_NAME:      /appnetos/index.php
REQUEST_URI:      /appnetos/docs/core?language=en
Stored request URI: /appnetos/docs/core?language=en
Stored path:        /docs/core
Stored segments:    ["docs", "core"]

If no usable request URI is provided, the bootstrap defaults to / with an empty segment list. Removing the public subdirectory does not alter the preserved original URI.

Process Runtime Initialization

When ProcessInput is supplied, RuntimeBootstrap marks the runtime as a process and copies its already resolved input fields into the shared state. The HTTP initialization branch is skipped.

Runtime field Source
Process flag true
Executable ProcessInput::getExecutable()
Operation ProcessInput::getOperation()
Arguments ProcessInput::getArguments()
Application ProcessInput::getApplication()
Context ProcessInput::getContext()

This branch is used for command and worker execution. HTTP-specific values are not initialized here; their fields retain their RuntimeState defaults.

Configuration and Environment

RuntimeBootstrap has no dedicated configuration file. It copies the values already validated and defined by Environment Bootstrap into RuntimeState.

protected function initEnvironment(RuntimeState $runtimeState): void
{
    $runtimeState->setEnvironment(APPNETOS_ENVIRONMENT);
    $runtimeState->setSecret(APPNETOS_SECRET);
    $runtimeState->setDebug(APPNETOS_DEBUG);
}

The runtime state receives these values; it does not reload .env.php or resolve additional environment-specific files. Environment configuration remains the responsibility of the first bootstrap step.

Security and Implementation Boundaries

  • RuntimeState is final and belongs to the protected bootstrap chain.
  • RuntimeStateHolder must remain a lightweight static reference, not a second state service.
  • RuntimeState setters support internal initialization; they are not an application configuration mechanism for changing the protected environment settings.
  • Runtime ID generation uses random_bytes(16) and can raise RandomException if secure randomness is unavailable.
  • Host and forwarded-protocol values originate from the HTTP server environment and require trustworthy upstream configuration.

Next Steps

Previous

Error Handling

Explore Error Handling

Next

Application

Explore Application