Request Processing Pipeline

This document describes how HTTP requests flow through the Light framework's processing pipeline, from initial receipt to response generation. It covers the middleware pipeline architecture, request preprocessing, authentication setup, and GraphQL execution.

For information about the App class initialization and service setup, see App Class. For details on GraphQL query execution and schema generation, see GraphQL API. For authentication and authorization logic, see Authentication and Authorization.

---

Overview

The request processing pipeline in Light follows the PSR-15 middleware pattern. Each incoming HTTP request passes through the following stages:

1. Server Reception: The Light\Server instance receives the PSR-7 request
2. Middleware Processing: The Light\App class acts as middleware, preprocessing the request
3. Request Handling: The Light\App class acts as the final handler, executing GraphQL queries
4. Response Generation: JSON responses are generated with appropriate debug information

The Light\App class serves dual roles: it implements both MiddlewareInterface for preprocessing and RequestHandlerInterface for final request handling.

Sources: src/App.php34

---

Server Architecture

Light\Server and PSR-15 Pipeline

The framework uses the Light\Server class (from the mathsgod/light-server package) to manage the PSR-15 middleware pipeline. The server is initialized in the App constructor and configured to pipe the App itself as middleware:

Server Initialization and Pipeline Setup

The server is created and configured during App construction:

• new \Light\Server($this->container) creates the server instance with dependency injection support
• $this->server->pipe($this) adds the App as middleware to the processing pipeline
• The server manages request/response flow through the Laminas Stratigility middleware pipeline

Sources: src/App.php63-65

---

Middleware Layer: App::process()

The process() method in Light\App implements the MiddlewareInterface, performing essential preprocessing before the request reaches the final handler. This method handles several critical tasks in sequence.

Processing Sequence Diagram

Sources: src/App.php475-528

OPTIONS Request Handling

The first operation in the processing pipeline is handling CORS preflight requests. OPTIONS requests receive an immediate empty 200 response without further processing:

This allows browsers to perform CORS preflight checks efficiently.

Sources: src/App.php477-479

JSON Body Parsing

If the request body hasn't been parsed yet, the middleware parses it as JSON:

This ensures GraphQL queries sent as JSON payloads are available in the parsed body.

Sources: src/App.php481-484

File Upload Processing

The UploadMiddleware from the ecodev/graphql-upload package processes multipart form data for file uploads according to the GraphQL multipart request specification:

This transforms uploaded files into a format compatible with GraphQL mutations that accept file inputs.

Sources: src/App.php486-487

Request Attribute Assignment

The App instance is attached to the request as an attribute, making it accessible to downstream handlers:

This allows other components to access the App instance and its services.

Sources: src/App.php489

Authentication Service Initialization

A critical step in the pipeline is initializing the authentication service:

The Auth\Service is responsible for:

• Determining the current authenticated user from JWT tokens in cookies
• Providing authentication and authorization checks to GraphQLite
• Being available for dependency injection throughout the application

Sources: src/App.php499-506

Drive File Serving

For authenticated GET requests with paths starting with drive/, the middleware handles file serving directly:

The path format is drive/{index}/{filepath} where:

• {index} is the filesystem configuration index
• {filepath} is the file path within that filesystem

The getDriveResponse() method retrieves the file using Flysystem and returns it with appropriate content-type headers.

Sources: src/App.php508-526 src/App.php531-553

---

Request Handler: App::handle()

After passing through middleware preprocessing, requests that aren't served directly are passed to the handle() method, which implements RequestHandlerInterface.

GraphQL Execution Flow

Sources: src/App.php131-150 src/App.php556-567

Query Execution

The execute() method performs GraphQL query execution:

Key steps:

1. File upload middleware is applied again to ensure file handling is properly set up
2. GraphQL query and variables are extracted from the parsed request body
3. The schema is created from the schema factory (with cached type definitions)
4. GraphQL::executeQuery() from webonyx/graphql-php executes the query against the schema
5. A new Context object is created to hold execution context

Sources: src/App.php556-567

Response Generation

The handle() method wraps the execution result in a JSON response:

Response behavior:

• Development mode: Includes debug messages and stack traces in the response for troubleshooting
• Production mode: Returns only essential error information
• Exception handling: Catches any exceptions and returns them as GraphQL error responses

The mode is determined by the mode configuration value stored in the Config table.

Sources: src/App.php131-150 src/App.php569-572

---

Complete Request Flow Diagram

The following diagram shows the complete request processing pipeline with all major components and decision points:

Sources: src/App.php475-528 src/App.php131-150 src/App.php556-567

---

Key Components Summary

Component	Type	Role
Light\Server	PSR-15 Server	Manages middleware pipeline, routes requests
Light\App::process()	Middleware	Preprocesses requests, handles OPTIONS, sets up auth
Light\App::handle()	Request Handler	Executes GraphQL queries, generates responses
UploadMiddleware	Middleware	Processes multipart file uploads for GraphQL
Auth\Service	Service	Manages authentication state, provides user context
SchemaFactory	Factory	Creates GraphQL schema with type definitions
GraphQL::executeQuery()	Static Method	Executes GraphQL queries from webonyx/graphql-php

Sources: src/App.php34 src/App.php63-65 src/App.php114 src/App.php475-528 src/App.php131-150

---

Configuration Points

The request pipeline behavior can be configured through:

1. Mode (dev/prod): Set via the mode Config entry, controls debug output verbosity
2. JWT Secret: Environment variable JWT_SECRET used for token validation in Auth\Service
3. Cookie Settings: Environment variables COOKIE_DOMAIN, COOKIE_SECURE, COOKIE_SAMESITE, COOKIE_PARTITIONED control session cookie behavior
4. Filesystem Configuration: The fs Config entry defines available file system drives for serving

Sources: src/App.php98-112 src/App.php569-572 src/App.php621-634 src/App.php645-665