Light-Fabric

Light-Fabric is a high-performance, unified platform for managing the lifecycle, governance, and orchestration of enterprise AI services including agentic services, agents, tools, skills, memories, MCP servers, APIs, gateways and workflows.

Why Light-Fabric?

We chose the name Light-Fabric because it embodies the "Unified Governance" required for enterprise-grade AI:

• Unified Control Plane: Light-Fabric provides a single point of truth for discovering, governing, and auditing agents, MCP servers, and APIs via the light-portal.
• Enterprise Governance: It prioritizes security and policy enforcement (such as fine-grained authorization) over pure decentralized autonomy, making it safe for corporate environments.
• Integrated Ecosystem: It "weaves" together distributed components—from memory units (Hindsight) to centralized skills—into a cohesive, observable system.
• Durable Identity: The name emphasizes the platform's role as the infrastructure foundation, remaining relevant regardless of the underlying implementation details.

Technical Advantages

By building Light-Fabric on a Rust foundation, we achieve:

• Performance: Built on top of tokio and axum for maximum throughput and memory safety.
• Native Intelligence: Specialized crates for Hindsight memory, tool calling, and workflow orchestration.
• Production Ready: Includes robust features like retries, failover, and observability out of the box.

Core Components

The Light-Fabric is composed of modular crates, infrastructure frameworks, and reference applications:

Crates

• crates/model-provider: A unified interface for multiple LLM providers (Ollama, etc.).
• crates/hindsight-client: Client for the Hindsight biomimetic memory system.
• crates/mcp-client: Implementation of the Model Context Protocol (MCP) for tool discovery and execution.
• crates/portal-registry: Integration with the Light-Portal for service registration and discovery.
• crates/light-runtime: Core runtime foundation for building agentic and microservice components.
• crates/light-rule: High-performance rule engine for fine-grained authorization and data filtering.
• crates/workflow-core & workflow-builder: Core engine and builder for complex agentic workflows.
• crates/config-loader: Flexible configuration management for enterprise environments.
• crates/asymmetric-decryptor & symmetric-decryptor: Security utilities for sensitive data handling.

Frameworks

• frameworks/light-axum: A specialized microservice & agentic framework built on top of the Axum web ecosystem.
• frameworks/light-pingora: High-performance proxy and gateway framework built on top of Cloudflare's Pingora.

Applications

• apps/light-agent: A managed AI agent capable of using tools, accessing memory, and executing complex tasks.
• apps/light-gateway: An enterprise-grade gateway for securing and governing API and agent traffic.
• apps/light-workflow: A service for orchestrating and executing long-running agentic workflows.

Getting Started with Light-Fabric

This guide will help you set up a local development environment for Light-Fabric, including the AI Gateway, Agent Engine, and the management Portal.

Prerequisites

• Rust: Latest stable version.
• Docker: For running database and backend services.
• Node.js: For running the portal-view UI.
• Git: To clone the necessary repositories.

Local Development Setup

To run the entire ecosystem locally, we use the portal-config-loc and service-asset repositories to manage configuration and pre-built assets.

1. Initialize Workspace

Create a unified workspace directory (e.g., ~/lightapi) and clone the core management repositories:

cd ~
mkdir -p lightapi
cd lightapi

# Clone configuration and assets
git clone [email protected]:lightapi/portal-config-loc.git
git clone [email protected]:lightapi/service-asset.git

2. Deploy Local Services

Light-Fabric services are orchestrated via Docker Compose scripts in portal-config-loc. The following command starts the PostgreSQL database and the core services (including the Rust-based components):

cd ~/lightapi/portal-config-loc
./scripts/deploy-local.sh pg rust

3. Import Initial Data

Use the importer script in service-asset to populate the local database with initial events, users, and configurations:

cd ~/lightapi/service-asset
./importer.sh -f events.json

4. Update /etc/hosts

The platform uses virtual hosts for local routing. Add the following entry to your /etc/hosts file (replace with your actual local IP if necessary):

127.0.0.1  local.lightapi.net locsignin.lightapi.net

Running the Management Portal

The Light-Portal provides a unified UI for onboarding MCP servers, configuring AI Gateways, and interacting with agents.

cd ~/lightapi
git clone [email protected]:lightapi/portal-view.git
cd portal-view
npm install
npm run dev

Navigate to https://localhost:3000 and log in with your developer credentials.

Cloud Development (Coming Soon)

We are currently preparing a Cloud Development Server. This will allow developers to:

• Connect to a shared, high-performance AI Gateway.
• Onboard and test MCP servers without a full local installation.
• Collaborate on shared agentic workflows and Hindsight memory banks.

Stay tuned for the connection details and onboarding guide for the cloud environment.

Contributing to Light-Fabric

If you are developing for the Rust crates specifically:

cd ~/lightapi
git clone [email protected]:networknt/light-fabric.git
cd light-fabric
cargo build

Model Providers

Light-Fabric provides a unified, high-performance interface for interacting with diverse Large Language Model (LLM) providers. This abstraction is centered around the Provider trait, allowing applications to remain model-agnostic while leveraging advanced capabilities like native tool calling and prompt caching.

The Provider Trait

All model integrations implement the Provider trait, which supports:

• One-shot and Multi-turn Chat: Simplified APIs for simple prompts and full conversation histories.
• Structured Tool Calling: Native integration for function calling (OpenAI-style).
• Capabilities Detection: Programmatic checks for vision, native tool support, and prompt caching.

Supported Cloud Providers

Light-Fabric supports all major LLM providers. Because the Provider trait is model-agnostic, the framework is compatible with the latest flagship releases as soon as they are available.

• OpenAI: Native support for the GPT-5 series (5.4, mini, nano), the o4 reasoning models, and full legacy support for GPT-4o and GPT-4 Turbo.
• Anthropic: Support for the Claude 4 generation, including Opus 4.7, Sonnet, and Haiku.
• Google Gemini: Support for Gemini 3.1 Pro and Flash, leveraging Vertex AI or AI Studio for multi-modal and long-context tasks.
• Azure OpenAI: Enterprise-grade OpenAI deployments with support for the latest model deployments.
• AWS Bedrock: Access to the latest Claude and Titan models hosted on Amazon Web Services.
• OpenRouter: Access to hundreds of open-source and proprietary models via a single unified API.
• Telnyx: Support for models hosted on the Telnyx platform.
• GLM (Zhipu AI): Support for the ChatGLM/GLM-5 series of models.

Local & Specialized Providers

• Ollama: Seamless integration with local models running on your machine.
• OpenAI-Compatible: A generic CompatibleProvider for any service implementing the OpenAI REST API.
• GitHub Copilot: Integration with GitHub Copilot Chat for developer-centric workflows.

Meta-Providers (Orchestration)

These providers wrap other providers to add resilient or intelligent behavior:

• ReliableProvider: Enhances any base provider with retries, exponential backoff, and automatic failover to fallback models.
• RouterProvider: Dynamically routes requests to different models based on hints or input complexity.

CLI & Tooling Integrations

Light-Fabric includes specialized integrations for developer tools and terminal environments:

• Claude Code CLI: Integration with Anthropic's Claude Code environment.
• Gemini CLI: Terminal-based access to Google's Gemini models.
• KiloCLI: Light-Fabric's native CLI integration for rapid testing and automation.

Key Capabilities

Providers can be queried for their support of advanced features:

• Native Tool Calling: Efficiently generate structured function calls.
• Vision: Process images alongside text prompts.
• Prompt Caching: Leverage provider-side caching to reduce latency and costs for long contexts.

Agentic Workflow Design

Hybrid Agentic Workflow Specification

Agentic Workflow in Light-Fabric implements a hybrid orchestration model for enterprise business processes. The workflow is deterministic, auditable, and stateful, while selected steps can be executed by agents, API calls, rule engine checks, or humans.

The design goal is not to replace enterprise process control with an open-ended agent loop. The goal is to let agents work inside a managed process that has clear state, clear ownership, repeatable execution, and human approval where needed.

Enterprise Challenge

In regulated or operationally sensitive environments, a purely autonomous AI agent is not enough for long-running business work.

• Compliance requires deterministic process paths, approval records, and audit history.
• Reliability requires long-running state to survive process restarts, UI disconnects, and agent failures.
• Safety requires human-in-the-loop checkpoints for decisions with business, security, or financial impact.
• Coordination requires multiple humans and roles to participate in the same process.
• Testing requires the same workflow to run interactively with humans or headlessly with example data.

Light-Fabric solves this by separating orchestration from execution.

Hybrid Model

The workflow is the deterministic process manager. It defines the ordered steps, conditions, retries, error handling, human checkpoints, and outputs.

Agents are workers inside that process. They can reason, call tools, ask for missing data, and use skills, but they do not own the overall process state.

Core Separation

There are two related specifications:

1. Agentic Workflow Specification Describes orchestration: task order, branching, human input, assertions, API calls, retries, errors, exports, and state transitions.

2. LightAPI Description Specification Describes API capabilities at the endpoint level: how an endpoint is invoked, what inputs it accepts, what result shape it returns, examples, behavior notes, and result expectations.

This separation is important. The workflow should not duplicate every endpoint contract. It should reference endpoint descriptions and use them to invoke calls, guide agents, and verify results.

Endpoint-Level Consumption

Light-Portal manages API descriptions at the endpoint level, not only at the whole API level.

This is necessary because real workflows often combine one endpoint from one API with one endpoint from another API. For example, onboarding an API to an AI gateway may involve:

1. register an API
2. create an API version from a specification
3. create a development API instance
4. configure the API through config server
5. link the API instance to a gateway instance
6. select endpoints to expose as MCP tools
7. create a gateway config snapshot
8. reload the gateway through controller
9. run MCP tests against the gateway

Each step may come from a different API surface. The workflow consumes only the endpoints it needs.

The recommended model is:

• API-level descriptions can be authored for convenience and consistency.
• Endpoint-level descriptions are published and consumed by agents and workflows.
• Endpoint descriptions inherit shared context such as authentication, environments, sources, and secrets from an API catalog.
• Agents progressively load endpoint information by disclosure level instead of receiving the entire catalog up front.

Progressive Disclosure

Endpoint descriptions should be disclosed to agents in layers:

• index: operation id, title, tags, visibility
• summary: purpose, capability group, lifecycle
• invocation: input shape, request mapping, auth, examples
• behavior: result cases, errors, edge cases, assertions
• full: complete description for debugging or generation

This allows the agent to discover capabilities cheaply, load invocation details only for selected endpoints, and load behavior details only when verification or failure analysis needs it.

Workflow Task Types

The updated workflow specification adds first-class support for the task types needed by agentic API workflows.

Ask Task

ask pauses the workflow and waits for human input. It supports prompts, choices, validation, defaults, timeouts, and sensitive input.

The task returns the user's answer as task output. The normal export block should move the answer into workflow context.

Example:

- ask-authz:
    ask:
      prompt: Do you want to configure endpoint authorization?
      mode: choice
      options:
        - label: Configure authorization
          value: configure
        - label: Skip
          value: skip
    export:
      as:
        authzChoice: ${ .result }

Assert Task

assert validates workflow state or API results. It is used for both live tests and interactive workflows.

It supports simple comparisons, JSONPath-style checks, length checks, regex checks, and rule-engine-backed assertions for complex business logic.

Assertion failures should produce structured, catchable errors so workflows can route failures to remediation, task creation, or agent investigation. Complex business assertions can delegate to Light-Rule.

API Call Tasks

The workflow supports direct and description-backed API calls:

• HTTP / OpenAPI
• JSON-RPC
• OpenRPC
• gRPC
• MCP tool/resource/prompt calls

For direct internal calls, jsonrpc can be used with an endpoint, method, params, id, notification flag, and error policy.

For cataloged JSON-RPC, openrpc references an OpenRPC document and method.

For MCP, the workflow references a tool, resource, or prompt and passes arguments. MCP capability descriptions belong in the API description layer; the workflow only selects and invokes them.

Explanation Metadata

Tasks can include explain metadata to help an agent or UI explain what is happening.

Useful fields include:

• purpose
• visible
• before
• success
• failure
• requires

Example:

explain:
  purpose: Link the API instance to the development gateway.
  visible: true
  requires:
    - portal-command-token authentication
    - apiInstanceId from prior step

Human Task State

Human-in-the-loop behavior must be represented as durable workflow state.

Recommended task states:

A = active
W = waiting for input
C = completed
F = failed
X = canceled

When an ask or approval task reaches W, the process remains active but the task is no longer picked up by the executor. A user, CLI, scheduler, or agent must complete the task through the workflow API.

Waiting tasks should carry:

• prompt
• input mode
• options
• validation rules
• default value
• sensitive flag
• assignment metadata
• explanation metadata
• timeout policy

Assignment And Worklist

Enterprise workflows need more than chat. Some tasks must be assigned to roles or users and coordinated across multiple humans.

Human tasks should support:

• assigned user
• assigned role
• candidate roles
• claimed by
• claimed timestamp
• due timestamp
• priority
• comments
• audit trail

A role-based task appears in the worklist for users with a matching role. Once claimed, it belongs to the claiming user until completed, released, delegated, or timed out.

Client Architecture

light-workflow should run as a containerized backend service alongside other portal services. It owns workflow execution and state. Portal chat, worklist, CLI, scheduler, and agents are all clients of the same workflow APIs.

The client surfaces are:

• Portal Chat: conversational guidance for a single user.
• Worklist: role-based task inbox for approvals, reviews, and coordination.
• CLI: developer, CI/CD, live test, and automation interface.
• Scheduler: periodic headless execution, such as hourly live integration tests.
• Agent: task executor that can call APIs, use skills, and report results back to the workflow.

See Workflow Client Architecture for the dedicated client design.

Workflow Service API

The workflow service should expose one stable API boundary for all clients.

Core operations:

workflow.start
workflow.getInstance
workflow.listInstances
workflow.getEvents
workflow.listTasks
workflow.getTask
workflow.claimTask
workflow.releaseTask
workflow.completeTask
workflow.delegateTask
workflow.cancelInstance

Streaming clients should subscribe to workflow events through Server-Sent Events, WebSocket, or another portal-standard event mechanism.

Important event types:

• workflow started
• task started
• task completed
• task failed
• task waiting for input
• task assigned
• task claimed
• task completed by human
• agent started
• agent completed
• workflow completed
• workflow failed

Live Testing

The same workflow runtime should support interactive runs and headless live tests.

Interactive workflows use ask tasks when decisions or missing values are needed.

Live tests should use example data from LightAPI endpoint descriptions and workflow input fixtures instead of asking the user. Assertions should verify results through assert tasks or rule-engine checks.

This lets the scheduler run workflows every hour against the latest deployed services. When a test fails, the workflow can create a task with the failure detail and assign an agent or human to investigate.

Example: API Onboarding To AI Gateway

An API onboarding workflow can guide a user through a complex multi-endpoint process without requiring a dedicated UI for every operation.

The workflow can:

1. ask for or infer the API metadata
2. call the register API endpoint
3. create an API version from an OpenAPI specification
4. create a development API instance
5. configure the API
6. ask whether fine-grained authorization should be configured
7. route to create or select authorization rules
8. link the API instance to the development AI gateway
9. select endpoints to expose as MCP tools
10. create a gateway config snapshot
11. reload the gateway through controller
12. run MCP tests through the gateway
13. assert expected results
14. report success or create remediation tasks

The same workflow can run interactively through portal chat, be managed through the worklist, or run headlessly with examples as a live test.

Technical Implementation

The Light-Fabric implementation is split across:

• workflow-core: Rust models for the workflow specification.
• workflow-builder: fluent builders for programmatic workflow construction.
• light-workflow: runtime service and executor.
• light-agent: agent execution surface for delegated agent tasks.
• light-rule: rule engine used by workflow and assertion tasks. See Light-Rule Design.

Runtime responsibilities include:

• deserializing workflow definitions
• claiming active tasks
• executing supported task types
• storing task output
• applying exports into process context
• creating next tasks
• pausing waiting tasks
• resuming after human completion
• failing or completing process instances
• exposing workflow APIs to clients

The current executable slice supports API invocation and verification tasks such as HTTP, JSON-RPC, OpenRPC, MCP over enterprise HTTP transports, rules, assertions, and waiting human input. MCP stdio transport is intentionally not a priority for enterprise deployment.

Design Rule

There must be one workflow runtime and one task state model.

Chat, worklist, CLI, scheduler, and agents should never implement their own workflow execution. They should all use the same light-workflow service APIs.

This keeps enterprise workflow behavior auditable, testable, and consistent regardless of how a process is started, resumed, or observed.

Workflow Client Architecture

Light-Fabric workflow execution should run as a containerized backend service, not as logic embedded in a portal screen, CLI, scheduler, or agent. The workflow service owns process state, task state, audit records, API invocation, agent invocation, and human-in-the-loop transitions. Clients are thin interaction surfaces over the same service APIs.

This separation lets the same workflow instance be driven by a portal chat session, a worklist user, a CLI command, a scheduler, or an AI agent without creating multiple execution models.

Goals

• Provide one authoritative workflow runtime for long-running enterprise processes.
• Support human-in-the-loop tasks from both conversational and worklist interfaces.
• Support headless execution for live tests, scheduled runs, and CI/CD.
• Keep all clients stateless or lightly stateful; workflow state lives in light-workflow.
• Make role assignment, audit, and retry behavior consistent across UI, CLI, scheduler, and agent use.

Runtime Service

light-workflow should be deployed as a portal service in a container alongside the other portal services. It should expose APIs for workflow definitions, workflow instances, task claiming, task completion, event streaming, and operational control.

The service is responsible for:

• loading workflow definitions
• starting workflow instances
• persisting process_info_t and task_info_t
• executing API calls and assertions
• invoking agents for agent-owned tasks
• pausing on ask and approval tasks
• assigning human tasks to users or roles
• resuming workflows when a human answer is submitted
• emitting workflow and task events
• recording audit history

Clients should never execute workflow steps themselves. They should only start workflows, inspect workflow state, and complete assigned tasks.

Client Surfaces

Portal Chat

The portal chat client is the guided conversational interface for a single user working through a process. It is useful when the workflow needs to ask clarifying questions, explain the next action, or guide a user through a complex multi-endpoint operation.

Typical uses:

• API onboarding
• API endpoint publication to an AI gateway
• guided configuration
• troubleshooting and remediation workflows
• interactive approval with explanation

The chat client should call the workflow service for current state and submit answers to waiting tasks. It may stream workflow events and render agent explanations, but it should not own workflow state.

Worklist

The worklist is the enterprise task inbox. It is the right interface for multi-user coordination, role-based assignment, approvals, escalations, and audit-sensitive operations.

Typical uses:

• approval tasks
• compliance review
• operations handoff
• role-based queue processing
• task claim and release
• delegated work
• due-date and priority management

The worklist should be built around waiting human tasks. A task may have:

• assigned user
• candidate roles
• assigned role
• priority
• due time
• claim status
• comments
• completion payload
• audit trail

The worklist is especially important because many enterprise workflows are not purely conversational. They need accountable ownership and coordination between multiple humans.

CLI

The CLI is a developer and automation client. It should use the same workflow service APIs as portal-view and should not contain separate execution logic.

Typical uses:

• local workflow testing
• live parity tests
• CI/CD automation
• scheduled headless runs
• debugging stuck workflow instances
• submitting test data
• completing simple waiting tasks from scripts

Example commands:

light-workflow start portal.onboard-api --input input.yaml
light-workflow status <instance-id>
light-workflow tasks --role portal-admin
light-workflow claim <task-id>
light-workflow answer <task-id> --value approve
light-workflow logs <instance-id>
light-workflow cancel <instance-id>

The CLI should be added after the workflow APIs stabilize. It will be valuable for developers and automation, but the worklist and portal chat should drive the primary enterprise UX.

API Boundary

The workflow service should expose a stable API boundary that all clients use. The API can be HTTP, JSON-RPC, or both, but the concepts should remain the same.

Core operations:

workflow.start
workflow.getInstance
workflow.listInstances
workflow.getEvents
workflow.listTasks
workflow.getTask
workflow.claimTask
workflow.releaseTask
workflow.completeTask
workflow.delegateTask
workflow.cancelInstance

For streaming clients, the service should expose workflow events through Server-Sent Events, WebSocket, or another portal-standard event mechanism.

Important event types:

• workflow started
• task started
• task completed
• task failed
• task waiting for input
• task assigned
• task claimed
• task completed by human
• agent started
• agent completed
• workflow completed
• workflow failed

Human Task State

ask and approval-style tasks should enter a waiting state. While waiting, the workflow instance remains active, but the task is no longer executable by the worker loop until a human answer is submitted.

Recommended states:

A = active
W = waiting for input
C = completed
F = failed
X = canceled

The waiting task should include enough metadata for all clients:

• prompt
• input mode
• options
• validation rules
• default value
• sensitivity flag
• assignment metadata
• explanation metadata
• timeout policy

The completion API should validate submitted input against the task definition before resuming the workflow.

Assignment Model

Human tasks should support both direct assignment and role-based queues.

Recommended fields:

assigned_user
assigned_role
candidate_roles
claimed_by
claimed_ts
due_ts
priority
comments

A role-based task can appear in the worklist for all users with a matching role. Once a user claims it, the task becomes owned by that user until completed, released, delegated, or timed out.

Recommended Build Order

1. Implement stable workflow service APIs for start, status, events, task list, task claim, and task completion.
2. Harden the ask resume path and waiting task state machine.
3. Build the worklist because it forces the assignment, audit, and state model to be correct.
4. Build the portal chat workflow interaction on top of the same task APIs.
5. Add the CLI after the API shape stabilizes.
6. Add scheduler integration for hourly live tests and headless workflow runs.

Design Rule

There must be one workflow runtime and one task state model. Chat, worklist, CLI, scheduler, and agents are only clients of that runtime.

This keeps enterprise workflow behavior auditable, testable, and consistent regardless of how a workflow is started or resumed.

LightAPI Description Design

lightapi-description-specification

LightAPI Description is the endpoint capability specification used by Light-Fabric agents, workflows, live tests, and portal API administration.

It describes how an API endpoint is discovered, invoked, explained, and verified. It is intentionally separate from the Agentic Workflow Specification. Workflow describes process orchestration. LightAPI describes endpoint capability.

Why LightAPI

OpenAPI is useful for REST APIs, and OpenRPC is useful for JSON-RPC APIs, but Light-Fabric needs a common description model across multiple enterprise protocols:

• REST / HTTP
• OpenAPI-described HTTP
• JSON-RPC 2.0
• OpenRPC-described JSON-RPC
• gRPC
• MCP tools, resources, and prompts

LightAPI provides a single agent-facing and workflow-facing description layer over these protocols.

The goal is not to replace OpenAPI or OpenRPC. The goal is to reference them where they exist and add the missing information needed by agents and workflow live tests.

API-Level Authoring, Endpoint-Level Consumption

Light-Portal may let teams author descriptions at the API level for convenience. However, workflows and agents consume descriptions at the endpoint level.

This distinction is important because real workflow processes rarely use a whole API. They usually combine selected endpoints from multiple APIs.

For example, onboarding an API to an AI gateway may consume:

• one endpoint from API registration
• one endpoint from API version management
• one endpoint from API instance management
• one endpoint from config server
• one endpoint from gateway linking
• one endpoint from controller reload
• one or more MCP tools exposed through the gateway

Each consumed operation should have an endpoint-level description with a stable endpointId.

API-level descriptions are still useful as catalogs. Endpoint-level descriptions may inherit shared API context such as:

• environments
• authentication
• secrets
• sources
• common tags
• lifecycle metadata

Relationship To Agentic Workflow

Agentic Workflow and LightAPI have different responsibilities.

In live tests, the workflow should use example data from LightAPI descriptions and workflow fixtures instead of asking for user input.

In interactive runs, the workflow may ask the user for missing values, then invoke endpoints described by LightAPI.

Relationship To Centralized Agent Skills

LightAPI endpoint descriptions are a source of agent skills.

The centralized skill registry should not require every API operation to be manually rewritten as a separate skill. Instead, Light-Portal can publish selected LightAPI endpoint descriptions into the skill registry as invokable capabilities.

The skill registry adds:

• permission-aware discovery
• semantic search
• skill grouping
• agent persona scoping
• audit around skill disclosure and execution

LightAPI provides:

• endpoint identity
• protocol details
• input schema
• request mapping
• result shape
• examples
• behavior notes
• result cases

Together, they allow an agent to discover a capability as a skill, progressively load only the endpoint details it needs, and execute through the workflow or controller runtime.

See Centralized Agentic Skill Registry for the skill registry design.

Core Document Concepts

A LightAPI document should support both API-level catalogs and endpoint-level documents.

Important top-level concepts:

• lightapi: specification version
• profile: api or endpoint
• info: name, title, version, namespace, owner, contact
• context: inherited catalog context for endpoint-level documents
• sources: OpenAPI, OpenRPC, protobuf, MCP, or raw protocol references
• environments: environment-specific server details
• secrets: required secret names
• authentications: reusable authentication policies
• operations: endpoint operation descriptions
• testSequences: linear endpoint test sequences
• agent: progressive disclosure and skill metadata

For profile: endpoint, the document should describe at most one operation.

Operation Model

Each operation represents one endpoint-level capability.

Common fields include:

• operationId: local operation identifier
• endpointId: globally stable endpoint identifier
• title
• summary
• description
• visibility
• lifecycle
• tags
• capability
• agent
• input
• request
• result
• examples

The input section describes the logical interface the agent or workflow sees.

The request section describes how logical input maps to the wire protocol.

The result section describes expected output, result cases, and failure shapes.

Protocol Coverage

HTTP And OpenAPI

For raw HTTP, the operation describes method, endpoint, headers, query, path, and body mappings.

For OpenAPI, LightAPI references the OpenAPI document and operation, then adds agent-oriented behavior, examples, and result expectations.

JSON-RPC And OpenRPC

For direct JSON-RPC, the operation describes endpoint, method, params, id behavior, notification behavior, and error policy.

For OpenRPC, LightAPI references the OpenRPC document and method. The workflow runtime can use the OpenRPC document to validate that the method exists and that required params are present before calling it.

gRPC

For gRPC, the operation describes service, method, protobuf source, transport, metadata, request mapping, and result mapping.

For browser or gateway-mediated enterprise deployments, gRPC over WebSocket can be represented as a transport on the structured protocol operation.

MCP

For MCP, the operation describes tool, resource, or prompt invocation.

Tool listing alone is not enough. The description must also include:

• input schema
• result shape
• examples
• behavior differences for important input cases
• error cases
• verification expectations

MCP stdio is not a priority for enterprise portal deployment. HTTP and streamable HTTP transports should be the main runtime targets.

Result Cases And Verification

LightAPI should describe expected result behavior, but Agentic Workflow should execute the actual assertions.

This keeps verification orchestration in one place.

Recommended model:

• LightAPI operation result cases describe expected outputs, failure shapes, and examples.
• Workflow test steps invoke the operation.
• Workflow assert tasks verify actual output against expected result cases.
• Complex business checks can call the rule engine.

This allows the same endpoint description to support:

• agent skill usage
• workflow execution
• live integration testing
• failure diagnosis

Progressive Disclosure For Agents

A LightAPI document should support progressive disclosure so an agent can load only the information needed at each stage.

Recommended levels:

• index: endpoint id, title, tags, visibility
• summary: purpose, capability group, lifecycle
• invocation: input schema, request mapping, authentication, examples
• behavior: result cases, edge cases, errors, assertions
• full: complete endpoint description

The portal can expose query APIs such as:

lightapi.listOperations
lightapi.getOperation
lightapi.getCapabilityGroup

Agents should start with index or summary data, load invocation details only for selected endpoints, and load behavior details only for testing, troubleshooting, or failure repair.

Portal Publishing Flow

Light-Portal should manage endpoint descriptions as part of API endpoint administration.

Recommended flow:

1. API owner creates or imports API metadata.
2. Portal extracts initial endpoint descriptions from OpenAPI, OpenRPC, protobuf, MCP, or raw endpoint configuration.
3. API owner enriches endpoint descriptions with examples, behavior notes, result cases, and visibility.
4. Portal stores endpoint-level LightAPI descriptions.
5. Authorized agents and workflows query descriptions by endpoint, tag, lifecycle, visibility, or capability.
6. Selected endpoints can be published into the centralized skill registry.
7. Workflow instances reference endpoint descriptions during execution and live testing.

Live Test Use

Live tests should be workflow-driven.

LightAPI supplies:

• example input data
• expected result cases
• protocol invocation details
• error behavior

Agentic Workflow supplies:

• sequence
• fixtures
• environment selection
• endpoint invocation
• assertions
• failure routing
• task creation
• agent assignment

This avoids building a second test runner model outside the workflow engine.

Design Rule

LightAPI describes endpoint capability. Agentic Workflow orchestrates endpoint use. Centralized Skills expose selected capabilities to agents.

Keeping these responsibilities separate lets Light-Fabric support API administration, agent skill discovery, workflow execution, and live integration testing without duplicating endpoint definitions across multiple systems.

Light-Rule Design

rule-specification

Light-Rule is the local YAML rule engine used by Light-Fabric services and workflows for deterministic business checks, transformations, authorization decisions, and workflow assertions.

It complements agentic workflow by keeping critical decisions explicit, repeatable, and auditable. Agents can propose or select rules, but the rule engine executes the deterministic logic.

Purpose

Light-Rule is designed for enterprise services that need fast local policy and transformation logic without a database call on every request.

Primary uses:

• fine-grained authorization
• request transformation
• response transformation
• workflow assertions
• business validation
• permission and filter injection
• reusable rule templates selected from Light-Portal

The rule configuration is loaded locally by the target service. When permissions or rule mappings change, the controller can trigger a config reload so the service swaps to the latest rules.

Relationship To Agentic Workflow

Agentic Workflow orchestrates process steps. Light-Rule evaluates deterministic logic inside those steps.

Workflow uses Light-Rule in two main ways:

1. Rule call task A workflow task can call a named rule to validate or mutate workflow context.

2. Assert task extension Simple checks can be handled directly by assert, while complex business checks can delegate to Light-Rule.

This separation keeps workflows readable. The workflow says when a check happens; Light-Rule defines the reusable business logic for the check.

Example workflow responsibilities:

• decide when authorization configuration is needed
• select or create a rule
• invoke a rule during live testing
• route failures to a human or agent

Example Light-Rule responsibilities:

• evaluate role, group, position, or attribute checks
• inject endpoint permissions into the context
• compute row or column filters
• execute transformation plugins
• return pass/fail for business assertions

See Agentic Workflow Design for the workflow orchestration model.

Relationship To LightAPI

LightAPI endpoint descriptions describe endpoint invocation and expected result behavior. Light-Rule can implement complex result checks that are too business-specific for simple schema assertions.

Recommended model:

• LightAPI describes endpoint result cases and expected behavior.
• Agentic Workflow invokes the endpoint and runs assert tasks.
• assert handles simple checks directly.
• Light-Rule handles complex checks, authorization logic, row filters, column filters, and reusable business policies.

See LightAPI Description Design for endpoint capability descriptions.

Rule Specification

Rules are described by the rule specification in rule-specification/schema/rule.yaml.

The top-level configuration contains:

• ruleBodies: named rule definitions
• endpointRules: endpoint-to-rule mappings

Each rule can contain:

• ruleId
• ruleDesc
• version
• author
• updatedAt
• conditions
• actions

Each endpoint mapping can contain:

• req-tra: request transformation rules
• res-tra: response transformation rules
• access-control: access control rules
• permission: permission values injected into context
• x-*: extension rule phases

Rule Conditions

Conditions evaluate fields in the input context.

Supported operand forms:

• direct field: role
• dotted path: user.role
• JSON Pointer: /user/role
• JSONPath-like path: $.user.roles[0]

Supported operators:

==
!=
>
<
>=
<=
eq
ne
contains
matches
startsWith
endsWith
exists
notExists

expected is typed and may be a string, number, boolean, array, object, or null.

Flat condition arrays are evaluated left-to-right. joinCode combines the current condition with the previous result.

A AND B OR C

is evaluated as:

(A AND B) OR C

If explicit grouping is required, split logic into multiple rules and combine them through endpoint mapping or workflow orchestration.

Rule Actions

Actions execute plugin logic after conditions pass.

An action contains:

• actionId
• actionClassName
• actionValues

actionClassName identifies the registered plugin. actionValues carries plugin-specific configuration.

Typical action plugins:

• add values to request context
• inject permission attributes
• compute filters
• transform request body
• transform response body
• call a local business function

Actions are intentionally plugin-based so the schema remains stable while implementation logic can evolve.

Endpoint Rule Phases

Endpoint mappings define when rules run.

Request Transformation

req-tra rules run before the service handles the request. They can enrich or transform request context.

Response Transformation

res-tra rules run after the service produces a response. They can filter, redact, or reshape response data.

Access Control

access-control rules validate whether a request is allowed. These rules normally run in parallel because they should not mutate shared state.

Permission Injection

permission values are injected into the evaluation context before rule execution. This lets API owners configure roles, groups, attributes, row filters, or column filters without editing the technical rule body.

Extension Phases

Custom phases must use the x-* prefix. This avoids silent typos in standard phase names while preserving controlled extensibility.

Execution Model

The Rust implementation lives in crates/light-rule.

Core components:

• RuleConfig: top-level config model
• Rule: rule definition
• RuleCondition: condition model
• RuleAction: action model
• RuleEngine: evaluates one rule
• ActionRegistry: maps action class names to plugins
• MultiThreadRuleExecutor: executes rule lists and endpoint phase mappings

Sequential phases such as req-tra and res-tra should run with all semantics so transformations happen in order.

Access control can run in parallel because it should be a validation step rather than a mutation step.

Why Not Replace With Cedar Or Casbin

Cedar and Casbin are strong policy engines, but Light-Rule has a different role in this platform.

Light-Rule supports:

• local YAML configuration
• request and response transformation
• permission injection
• row and column filters
• endpoint-specific rule selection
• technical-team-authored reusable rules
• API-owner-selected rule parameters
• config reload through controller

Cedar is excellent for authorization policy, but it does not naturally cover transformation, row filter, and column filter use cases. Casbin is strong for policy enforcement, but it introduces a different policy storage and matching model.

Light-Rule should remain the native rule engine for Light-Fabric service configuration and workflow assertions. External policy engines can still be integrated as action plugins if needed.

Governance

Rule bodies should be authored and reviewed like code or controlled configuration.

Recommended governance metadata:

• version
• author
• updatedAt
• ruleDesc

Recommended operational controls:

• validate rule YAML against the schema before publishing
• reject endpoint phase typos
• keep ruleId equal to the ruleBodies map key
• audit rule publication and reload events
• test rules with representative input contexts
• use workflow live tests to verify rules in integrated environments

Workflow Live Testing

Light-Rule is useful in live tests because it can express business checks that are more specific than generic JSON assertions.

Example flow:

1. Workflow invokes an endpoint using LightAPI description.
2. Workflow captures the endpoint response.
3. assert verifies simple fields.
4. A rule task validates business-specific behavior.
5. On failure, workflow creates a task for a human or agent to investigate.

This keeps live test orchestration in workflow while preserving reusable business rules in Light-Rule.

Design Rule

Use workflow for process control. Use LightAPI for endpoint capability. Use Light-Rule for deterministic business logic.

Agents may select, explain, or help author rules, but the rule engine should execute the final deterministic decision.

CEL Rule Conditions

Light-Rule should support both the existing native condition schema and CEL expressions. The two forms solve different problems and should share the same rule lifecycle, endpoint mapping, action execution, config loading, testing, and governance model.

The native condition schema remains the default because it is easy to render in Light-Portal, simple to validate, and suitable for most API-owner use cases. CEL is an advanced condition form for customers that need richer boolean logic, grouping, list predicates, or compatibility with existing CEL-based policy assets.

Each rule should choose one condition language: native or cel. Mixing native condition rows and CEL expressions inside the same rule is not recommended as the canonical model because it makes portal authoring, validation, and runtime dispatch harder to reason about.

Goals

• keep existing rule YAML and portal-authored rules compatible
• support CEL expressions as a rule-level condition language
• evaluate native and CEL rules in the same RuleEngine
• reuse the existing rule context for gateway, workflow, and test execution
• preserve existing actions, endpointRules, and rule phase semantics
• let Light-Portal choose the correct editor from rule metadata without parsing arbitrary rule bodies
• validate CEL before publishing or reloading rules where possible
• keep CEL execution deterministic and side-effect free

Non-Goals

• replacing the native Light-Rule condition schema
• replacing actions with CEL
• allowing CEL expressions to perform I/O, network calls, mutation, or service lookups
• making every native operator available as a custom CEL function on day one
• requiring business users to write CEL for common rules
• supporting mixed native and CEL condition blocks in the canonical portal authoring flow

Current Model

Today a rule contains an optional flat list of native conditions:

ruleBodies:
  allowMcpReader:
    common: Y
    ruleId: allowMcpReader
    ruleName: Allow MCP reader
    ruleType: req-acc
    conditions:
      - operatorCode: isNotNull
        propertyPath: auditInfo.subject_claims.ClaimsMap.role
    actions:
      - actionClassName: com.networknt.rule.RoleBasedAccessControlAction

Each native condition contains:

• operator
• operand
• expected
• joinCode

The engine evaluates conditions left-to-right. joinCode combines each condition with the accumulated result. If the final condition result is true, actions run as they do today.

Portal persistence stores rule metadata in rule_t and the executable rule JSON in rule_t.rule_body. Today there is no dedicated column that tells the portal which condition editor to render, so the UI would have to inspect rule_body.

Proposed Rule Shape

Add a rule-level condition language flag. Use native for existing condition rows and cel for a single CEL expression.

Persist the flag in both places:

• rule_t.condition_language: indexed/listable portal metadata
• ruleBody.conditionLanguage: self-contained exported runtime configuration

Recommended values:

native
cel

Existing rules without the field are interpreted as native.

Native rule body:

ruleBodies:
  allowMcpReader:
    common: Y
    ruleId: allowMcpReader
    ruleName: Allow MCP reader
    ruleType: req-acc
    conditionLanguage: native
    conditions:
      - operatorCode: isNotNull
        propertyPath: auditInfo.subject_claims.ClaimsMap.role
    actions:
      - actionClassName: com.networknt.rule.RoleBasedAccessControlAction

CEL rule body:

ruleBodies:
  allowApprovedTransfer:
    common: Y
    ruleId: allowApprovedTransfer
    ruleName: Allow approved transfer
    ruleType: req-acc
    conditionLanguage: cel
    conditionSecurityProfile: strict
    expression: >
      auditInfo.subject_claims.ClaimsMap.role != null
      && roles.exists(r, r == auditInfo.subject_claims.ClaimsMap.role)
    actions:
      - actionClassName: com.networknt.rule.RoleBasedAccessControlAction

Recommended database shape:

ALTER TABLE rule_t
ADD COLUMN condition_language VARCHAR(16) DEFAULT 'native' NOT NULL;

ALTER TABLE rule_t
ADD COLUMN condition_security_profile VARCHAR(32);

ALTER TABLE rule_t
ADD CONSTRAINT rule_t_condition_language_check
CHECK (condition_language IN ('native', 'cel'));

ALTER TABLE rule_t
ADD CONSTRAINT rule_t_condition_security_profile_check
CHECK (
  condition_security_profile IS NULL
  OR condition_security_profile IN ('strict', 'standard', 'internal-admin')
);

Recommended schema rules:

• conditionLanguage is optional and defaults to native
• conditionLanguage: native allows conditions and rejects expression
• conditionLanguage: cel requires expression and rejects conditions
• conditionSecurityProfile is optional and names a runtime-defined profile
• native conditions continue to require operator or operatorCode
• native conditions continue to require operand or propertyPath
• unknown rule and condition fields should continue to be rejected by the schema
• command handlers should reject requests where the DB metadata and rule body condition language disagree

This can be represented with conditional validation in rule-specification/schema/rule.yaml:

allOf:
  - if:
      properties:
        conditionLanguage:
          const: cel
      required: [conditionLanguage]
    then:
      required: [expression]
      not:
        required: [conditions]
    else:
      not:
        required: [expression]

The Rust model can add optional fields to Rule:

#![allow(unused)]
fn main() {
pub condition_language: Option<String>,
pub condition_security_profile: Option<String>,
pub expression: Option<String>,
}

This is less disruptive than changing RuleCondition into an enum and keeps old rule bodies valid.

Cross-Repository Scope

This change crosses the rule specification, runtime engines, portal services, and portal UI. The implementation should be tracked as a coordinated change rather than a light-fabric-only feature.

portal-db is listed even though it is not a rule engine because rule_t lives there. Without the DB column, portal-view would need to parse the compact rule body to choose the editor, which is the coupling this design is trying to avoid.

Operator Alias Alternative

Another possible shape is to add operatorCode: cel and store the CEL expression in expected inside conditions:

conditions:
  - operatorCode: cel
    expected: >
      context.toolArguments.amount < 1000
      || roles.exists(r, r == "approver")

This has one advantage: it can be implemented with a small Rust model change because operator, operand, and expected already exist. It is useful as a compatibility alias or import format.

It should not be the canonical schema because:

• CEL is a full boolean expression, not a comparison operator
• overloading expected makes validation and portal rendering less clear
• operand becomes ignored or artificial
• the UI still has to draw a condition-row editor even though the rule is really a single expression
• the rule schema still needs to change because the operator enum must include cel and native operand requirements must be relaxed
• future expression languages would continue overloading native condition fields

The recommended contract is therefore:

• canonical form: conditionLanguage: cel plus rule-level expression
• optional compatibility form: operatorCode: cel plus string expected
• normalize compatibility imports to the canonical rule-level model before persistence or runtime evaluation

Mixed Conditions Alternative

Another possible shape is to allow native and CEL conditions in the same conditions array. The runtime can support this if needed, but it should not be the default authoring model.

Reasons to avoid canonical mixed rules:

• Light-Portal would need a hybrid editor that switches row-by-row
• validation errors become harder to explain to non-technical users
• joinCode semantics across native and CEL expressions are correct but subtle
• users may expect CEL operator precedence inside the whole rule even though native joinCode remains left-to-right
• runtime dispatch is simpler and faster when the rule selects one evaluator

If mixed rules are ever accepted for import or advanced API use, joinCode should still apply left-to-right to the accumulated result regardless of which evaluator handled the current or previous condition.

Execution Model

Rule execution should dispatch by conditionLanguage once per rule:

RuleEngine::execute_rule
  -> conditionLanguage == native
     -> evaluate native conditions
  -> conditionLanguage == cel
     -> evaluate rule expression
  -> execute actions when conditions pass

The outer behavior stays unchanged:

• rules with no conditions continue to run actions
• CEL rules without an expression fail validation before runtime
• failed conditions skip actions
• failed action execution fails the rule
• endpoint rule ordering and access-control logic stay unchanged
• req-tra and res-tra continue to run sequentially
• access-control rules can still be evaluated independently

Runtime should treat a missing conditionLanguage as native for backward compatibility.

Rule Context

CEL should evaluate against the same JSON context used by native conditions. For gateway access-control and response filtering, this includes fields such as:

• auditInfo
• headers
• endpoint
• toolName
• toolArguments
• correlationId
• responseBody
• statusCode

Endpoint permission values are merged into the root context as their configured keys. For example, permission.roles in endpointRules is available to conditions as roles, response row filters are available as row, and column filters are available as col. A future runtime can also expose a namespaced permission object as an additive convenience, but CEL support should not require that shape to preserve compatibility with existing native rules and actions.

For standard and internal-admin profiles, the CEL environment can expose variables in two ways:

• top-level context fields as direct CEL variables, such as auditInfo, toolArguments, and roles
• the full root object as context, so expressions can use explicit paths such as context.toolArguments.amount

Direct variables keep expressions concise and close to the native condition path style. The context variable is safer for generated expressions, collision avoidance, and future fields that are not valid CEL identifiers.

For the strict profile, the runtime should expose only curated root variables such as auditInfo, headers, toolArguments, endpoint metadata, and permission values needed by the rule phase. It should not expose the full context object by default. This prevents future internal runtime metadata from becoming visible to tenant-authored CEL just because it was appended to the root request context.

The context contract should be documented as part of Light-Rule because CEL expressions depend on stable field names. Adding fields is compatible. Renaming or changing field shapes is a breaking change for CEL rules.

Type Mapping

The CEL evaluator should receive deterministic values converted from serde_json::Value:

• JSON object to CEL map
• JSON array to CEL list
• JSON string to CEL string
• JSON number to CEL integer or double
• JSON boolean to CEL bool
• JSON null to CEL null

Missing fields should evaluate according to the chosen CEL implementation's standard behavior. The rule test API should expose these failures clearly so authors can distinguish "expression false" from "expression invalid".

Authors should guard optional fields explicitly. Depending on the selected CEL runtime and the field shape, this can use presence checks such as has(...) or map membership checks such as:

"role" in auditInfo.subject_claims.ClaimsMap
  && auditInfo.subject_claims.ClaimsMap.role == "admin"

The portal rule tester should surface missing-field evaluation errors and suggest guarded expressions instead of letting these failures look like ordinary denied rules.

Context Injection Performance

CEL expressions run on request paths, so context conversion must be controlled. The implementation should not recursively deep-clone and convert large JSON payloads separately for every CEL rule evaluation.

Recommended approach:

• compile expressions once at rule load
• build the rule context once per request or response phase
• reuse converted CEL variables across evaluations in the same request or response phase when possible
• prefer lazy or reference-backed variable resolution if the selected CEL crate supports it
• if eager conversion is required, convert only the variables exposed to CEL and avoid parsing large string fields such as responseBody unless an expression explicitly needs structured access to them
• benchmark access-control and response-filter scenarios before enabling CEL by default in high-throughput paths

The initial implementation can be pragmatic, but performance tests should guard against accidentally making CEL expression evaluation proportional to the full response body size when the expression only needs claims or endpoint metadata.

Validation

CEL should be validated earlier than request execution.

Recommended validation points:

• portal rule editor
• rule command create/update handler
• rule test API
• runtime config reload

Validation must enforce mode-specific shape:

• native: conditions is allowed, expression is rejected
• cel: expression is required, conditions is rejected
• persisted rule_t.condition_language must match ruleBody.conditionLanguage
• persisted rule_t.condition_security_profile must match ruleBody.conditionSecurityProfile when either side is present

Runtime reload should reject invalid CEL when strict validation is enabled. If a service must preserve availability, it can keep the last known-good rule set and report the new config as rejected.

Approval workflow should not bypass validation. For profile escalation requests, the command path should validate the submitted rule shape and expression before creating the approval task. Final approval should revalidate the exact submitted rule body before emitting the active rule event.

Validation output should include:

• rule id
• condition language
• parse or type error
• source offset when provided by the CEL implementation

Compilation And Caching

Do not compile CEL on every request. Compile once per rule load and cache the compiled program with the loaded rule set.

Recommended cache key:

ruleId + expression hash + effective profile

The compiled expression cache should be replaced atomically when the rule config reloads. It should not outlive the rule version it was compiled from. Old compiled entries must be evicted during reload so repeated rule updates cannot leak memory through stale expression hashes.

Rust CEL Library

cel-interpreter is a practical first candidate for the Rust implementation. It provides Program::compile(...), Program::execute(...), a Context for variables and functions, and compiled Program values that are Send + Sync.

Implementation should still be isolated behind a small internal trait:

CelEvaluator
  -> compile(ruleId, expression) -> compiled expression
  -> evaluate(compiled expression, serde_json::Value context) -> bool

This keeps Light-Rule from leaking third-party crate types through its public model and allows the implementation to change if CEL crate maturity, feature flags, or Java parity requirements change.

Native Operator Parity

The native evaluator includes operators that may not map one-to-one to the selected CEL runtime. Examples include:

• containsIgnoreCase
• matches and notMatch
• inList and notInList
• containsAny, containsAll, and containsNone
• date-style comparisons such as before, after, and on

Before encouraging migration from native conditions to CEL, the implementation should define a small compatibility function registry for any gaps. Candidate pure helper functions include:

contains_ignore_case(value, substring)
matches(value, pattern)
in_list(value, values)
contains_any(value, values)
contains_all(value, values)

These functions must be deterministic, side-effect free, and shared by the rule tester and runtime evaluator. If Java parity is required, the same function names and edge-case behavior should be implemented in the Java runtime.

Safety

CEL support should be deterministic and sandboxed.

The evaluator does not need an operating-system sandbox for normal trusted/admin-authored rule configuration. CEL is an interpreted expression language, not arbitrary Rust or JavaScript execution, and expressions can only resolve variables and functions registered in the CEL context. The CEL context is therefore the primary sandbox boundary.

For the Rust cel-interpreter integration, context construction should be explicit. Context::default() exposes standard pure CEL functions such as size, contains, string helpers, type conversions, regex matches, and time parsing helpers depending on enabled crate features. If a service accepts tenant-authored or otherwise untrusted CEL, prefer Context::empty() and add only platform-approved helper functions.

Security policy should be engine-owned. A rule may request a named condition security profile, but it must not define its own function allowlist, size limits, resource limits, or isolation mode. If a rule author controls the rule body, then inline security settings are also attacker-controlled.

Recommended policy model:

runtime config defines profiles:
  strict
  standard
  internal-admin

rule optionally requests:
  conditionSecurityProfile: strict

effective policy:
  runtime maximum profile intersected with requested profile

If a rule omits conditionSecurityProfile, the runtime default applies. If a rule requests a profile that the service, tenant, or rule phase does not allow, the rule config should be rejected during validation or runtime reload. The engine may choose a stricter profile than requested, but it must never choose a weaker one because the rule requested it.

Recommended profiles:

• strict: default for tenant-authored, portal self-service, imported, or marketplace-style CEL. Use an empty CEL context, expose only approved variables, add only pure helper functions, and enforce tight size and expression-shape limits. Do not expose the full context root, and disable regex until both Java and Rust provide matching bounded or linear-time behavior.
• standard: default for internal business rules. Keep allowlists and resource limits, but permit common pure helpers such as size, contains, startsWith, endsWith, contains_ignore_case, and bounded regex support if needed.
• internal-admin: limited to trusted operator-maintained rules. This may be closer to the selected CEL runtime's default behavior, but should still compile during rule load, validate references, enforce maximum input size, and protect reloads with the last known-good rule set.

Allowed:

• boolean logic
• comparisons
• arithmetic supported by the CEL implementation
• string operations
• list and map predicates
• approved pure helper functions

Not allowed:

• file access
• network access
• database access
• current time unless explicitly added as an input field
• random values
• mutation of the rule context
• action execution from inside CEL

Custom functions should be added conservatively. Native Light-Rule actions remain the extension point for side effects and transformations.

The core runtime object should be a policy-driven condition evaluator rather than ad hoc logic embedded directly in RuleEngine:

RuleEngineOptions
  -> ConditionExecutionPolicy
      -> defaultCelProfile
      -> allowRuleProfileSelection
      -> profiles[name] = CelSecurityProfile

CelSecurityProfile
  -> allowedFunctions
  -> allowedRootVariables
  -> exposeContextRoot
  -> exposeTopLevelAliases
  -> maxExpressionBytes
  -> maxContextBytes
  -> maxStringBytes
  -> maxCollectionItems
  -> allowRegex
  -> allowTimeParsing
  -> allowComprehensions
  -> maxComprehensionNesting

CEL still needs resource and robustness controls because expressions run on request paths and can iterate over input data. Runtime and publish-time validation should:

• allow-list functions and variables, using compiled expression references where available
• reject functions that perform I/O, mutation, service lookup, action execution, random generation, or implicit current-time access
• cap expression length and input context size
• reject or limit expensive access to large request or response bodies
• compile during rule load and fail invalid expression shapes before request execution
• keep the last known-good rule set if reload validation fails

Phase ceilings should be enforced by runtime policy. Response phases such as res-tra and res-fil should default to a strict ceiling or tight maxContextBytes limits because they can include large response payloads. Access-control phases may allow standard only when the exposed context is small and bounded. A rule request for a stronger profile than the phase ceiling must be rejected or downgraded to the stricter effective profile.

For fully untrusted public input, evaluate CEL in a separate worker, process, or another resource-isolated execution path with CPU and memory limits. A Tokio timeout alone is not a complete guard for synchronous CPU-bound expression evaluation.

Portal Experience

Light-Portal should use conditionLanguage to choose the rule editor. This keeps the form predictable and avoids mixing two mental models on the same screen.

Recommended authoring modes:

• Builder: native condition rows with operand, operator, expected, and join controls
• CEL: advanced text area for one rule-level CEL expression

Recommended behavior:

• default new rules to native
• render condition subforms only for conditionLanguage: native
• render a CEL expression text area only for conditionLanguage: cel
• hide native condition controls when CEL is selected
• hide CEL expression controls when native is selected
• require confirmation when switching modes if the existing mode has content
• do not try to round-trip arbitrary CEL into native builder rows
• store the selected mode in rule_t.condition_language and in the JSON rule body as conditionLanguage
• for CEL rules, store only the selected profile name in rule_t.condition_security_profile and in the JSON rule body as conditionSecurityProfile; do not expose raw policy limits in the form
• do not show internal-admin in standard self-service forms; allow it only through checked-in runtime configuration or an explicitly authorized internal admin JWT/role path

The CEL editor should provide:

• syntax validation
• test context input
• expression result preview
• visible context field reference
• selected and effective security profile display
• rule test execution against the same backend evaluator used by runtime

Profile Approval Workflow

Light-Portal may allow a user to select a CEL security profile, but the selected profile is only a request. Runtime policy still computes the effective profile from the requested profile, the service maximum, the tenant maximum, and the rule phase ceiling.

Recommended publish behavior:

• strict: direct publish. If schema, CEL validation, and command authorization pass, create or update the rule immediately.
• standard: approval required. Submit the proposed rule change, create a worklist task for rule-admin and admin, and keep the change pending until approval.
• internal-admin: hidden from standard self-service authoring. If exposed to an operator-only flow, require stronger approval and never allow ordinary self-service users to request it.

For approval-required changes, the command side should not emit the final active RuleCreated or RuleUpdated event at submission time. It should emit a submission event such as RuleChangeSubmittedEvent or RuleApprovalRequestedEvent, store the proposed rule body and requested profile, and create the human-in-the-loop worklist task. Only approval should emit the active rule event. Rejection should emit a rejection event and leave the active rule unchanged.

Assistant tasks can help the approver by summarizing the CEL expression, rule phase, requested profile, referenced context roots, use of response body fields, regex usage, and any runtime ceiling that would downgrade the effective profile. The assistant output is advisory only; the human approver remains responsible for the approval decision.

Recommended approval rules:

• changing the expression, action list, rule phase, requested profile, or exposed context assumptions invalidates prior approval
• downgrading from standard to strict can publish directly after validation
• upgrading from strict to standard or internal-admin requires approval
• requester and approver should be different users except for an explicit break-glass workflow
• approval audit should record requested profile, effective profile, requester, approver, approval time, assistant-task summary id, and approval comments
• pending rules must not be exported to runtime endpoint rule config until approved

Compatibility

Existing rule YAML remains valid.

Rules without conditionLanguage are treated as native. The database migration should add rule_t.condition_language with default native, so existing rows do not need their rule_body rewritten immediately.

Rules without conditionSecurityProfile use the runtime default CEL profile. The field is meaningful only for CEL rules; native rules do not need a condition security profile.

Native condition aliases must continue to work:

• operatorCode as alias for operator
• propertyPath as alias for operand
• actionClassName as alias for actionRef

CEL introduces a new capability. If the Java yaml-rule runtime needs to execute the same rules, it must implement the same CEL rule shape. Until then, Java runtimes must fail closed with a clear capability error, such as UnsupportedConditionLanguageException, when loading or executing a rule with conditionLanguage: cel. A runtime must not silently ignore a CEL rule because that can fail open for access-control rules.

Java parity is feasible because Google maintains CEL-Java under the dev.cel Maven group, including the dev.cel:cel artifact with compiler and runtime APIs. The compatibility requirement is therefore mostly about aligning the rule schema, context shape, custom functions, and error handling across the Rust and Java runtimes.

Example: Access Control

ruleBodies:
  allowApprovedTransfer:
    common: Y
    ruleId: allowApprovedTransfer
    ruleName: Allow approved transfer
    ruleType: req-acc
    conditionLanguage: cel
    conditionSecurityProfile: strict
    expression: >
      auditInfo.subject_claims.ClaimsMap.role in roles
      && (
        toolArguments.amount < 1000
        || "transfer.approve" in auditInfo.subject_claims.ClaimsMap.scope
      )
    actions:
      - actionClassName: com.networknt.rule.RoleBasedAccessControlAction

endpointRules:
  /transfer@post:
    req-acc:
      - allowApprovedTransfer
    permission:
      roles:
        - teller
        - approver

Example: Response Filter Guard

ruleBodies:
  filterAccountsForPortalUsers:
    common: Y
    ruleId: filterAccountsForPortalUsers
    ruleName: Filter accounts for portal users
    ruleType: res-fil
    conditionLanguage: cel
    conditionSecurityProfile: strict
    expression: >
      statusCode == 200
      && responseBody != ""
      && auditInfo.subject_claims.ClaimsMap.role != null
    actions:
      - actionClassName: com.networknt.rule.ResponseRowFilterAction

Rollout Plan

1. Add rule_t.condition_language with default native, optional rule_t.condition_security_profile, and check constraints.
2. Extend the rule specification with native and CEL rule branches plus optional conditionSecurityProfile.
3. Add conditionLanguage, conditionSecurityProfile, and expression fields to the Rust Rule model.
4. Update command/query APIs so the portal can persist and read the condition language, security profile, and approval state without parsing ruleBody.
5. Optionally accept operatorCode: cel as an import/compatibility alias and normalize it to the rule-level CEL shape.
6. Choose and pin the Rust CEL crate behind an internal evaluator abstraction.
7. Add runtime-owned CEL security profiles and policy-driven context building.
8. Add approval workflow integration for standard and internal-admin profile requests, including worklist and assistant-task support.
9. Dispatch inside RuleEngine::execute_rule based on conditionLanguage.
10. Compile and cache CEL expressions during rule config load.
11. Add unit tests for CEL true, CEL false, invalid expression, mode validation, and missing-field behavior.
12. Add tests for custom native-parity helper functions.
13. Add performance tests for context conversion with large toolArguments and response payloads.
14. Add gateway integration tests using the existing rule context and the context root variable.
15. Add rule test API support so Light-Portal can validate CEL before publish.
16. Add portal mode-based rule editing, a controlled CEL profile selector, and approval UX for stronger profile requests.
17. Document runtime compatibility and Java parity requirements.

Decision

Support both condition languages. Native Light-Rule conditions remain the stable, portal-friendly default. CEL becomes an optional advanced expression language inside the same rule engine for customers that need richer policy expressions. A rule should select one condition language through conditionLanguage; mixed native/CEL condition arrays are not the canonical authoring model.

Design Document: Centralized Agentic Skill Registry

Subject: Transitioning from File-Based Markdown Skills to a Database-Backed Skill Registry

1. Executive Summary

Currently, most AI agent frameworks rely on localized Markdown (.md) files to define agent "skills." While Markdown is highly LLM-native and human-readable, it creates significant bottlenecks at an enterprise scale regarding strict typing, API integration, and context window limits.

This document proposes transitioning to an Agentic Control Plane (Centralized Skill Registry) backed by a database. By decoupling skill metadata, schemas, and instructions, and by utilizing dynamic routing, we will achieve hierarchical structuring, strict schema enforcement, and progressive disclosure of tools to agents.

2. Problem Statement

Managing agent skills as flat Markdown files introduces several scaling challenges:

1. Lack of Strict Typing: Markdown cannot enforce data types (e.g., ensuring a parameter is an integer vs. string), leading to hallucinated or malformed tool inputs.
2. Context Window Exhaustion: Loading dozens or hundreds of skill definitions at startup overwhelms the LLM context window, increasing latency, token costs, and tool-misuse.
3. Static Deployments: Updating a skill or changing access permissions requires a full application redeploy.
4. Poor Discoverability: Flat file structures offer no native mechanism for progressive disclosure or tool search.

3. Data Models & Formats

To solve the limitations of purely text-based skills, we will adopt a hybrid, structured format stored within a database (e.g., PostgreSQL/MongoDB). The architecture uses the right format for the right job:

• JSON Schema: Used strictly for defining parameters, inputs, and tool shapes. Natively supported by OpenAI/Anthropic/Google tool-calling APIs.
• LightAPI Description (YAML/JSON): Used to map endpoint-level API capabilities to skills across REST, JSON-RPC, gRPC, and MCP.
• OpenAPI / OpenRPC / Protobuf: Referenced by LightAPI where protocol-native specifications already exist.
• Executable Code (Python/JS) / URI: Stores the actual execution logic or the endpoint reference.
• Markdown: Retained only for the instructions or prompt fields, as LLMs excel at parsing markdown headers and lists for constraints and persona instructions.

LightAPI is the preferred source format for API-backed skills because it describes endpoint identity, protocol invocation, input schema, request mapping, result shape, examples, and behavior notes in one agent-oriented document. See LightAPI Description Design for the endpoint description model.

YAML and JSON are the external skill document formats. In the portal database, they should not replace the Markdown instruction field. The normalized model is structured columns and relationships for identity, versioning, taxonomy, tools, and execution metadata, plus content_markdown for the LLM-facing instruction body. If the portal later needs to persist a full structured skill document, add a nullable JSONB skill-spec column beside content_markdown and normalize YAML imports to JSON.

3.1 Proposed Database Schema Structure

Light Portal stores skills in structured catalog tables. Below is a representation of the skill payload:

{
  "skill_id": "sk_finance_001",
  "name": "generate_financial_report",
  "version": "1.2.0",
  "tags": ["finance", "reporting"],
  "tool_schema": {
    "type": "function",
    "function": {
      "name": "generate_financial_report",
      "description": "Generates a Q3 report based on ticker symbol.",
      "parameters": {
        "type": "object",
        "properties": {
          "ticker": {"type": "string", "description": "The stock ticker"}
        },
        "required": ["ticker"]
      },
      "response_schema": {
        "type": "object",
        "properties": {
          "report_url": {"type": "string"},
          "status": {"type": "string"}
        }
      }
    }
  },
  "execution": {
    "type": "rest_api",
    "endpoint_id": "ep_finance_report_001",
    "endpoint": "https://internal-api.company.com/v1/finance/report",
    "method": "POST"
  },
  "instructions": "## Role\nYou are a financial analyst.\n## Constraints\n- Never hallucinate financial data.\n- Always return exact numbers."
}

4. Hierarchical Structure & Progressive Disclosure

Dumping 500 JSON schemas into an LLM's context window will cause system failure. The Centralized Controller will act as a mediator, enforcing hierarchy and progressive disclosure (giving the agent only the schemas it needs, exactly when it needs them).

4.1 Implementing Hierarchy & Tagging

Because JSON Schema does not have built-in folders, hierarchy and categorization are enforced via the platform's global entity management system:

1. Namespacing: Tool names follow a strict convention: [domain]_[subdomain]_[action] (e.g., aws_rds_provision).
2. Tags & Categories: Instead of hardcoded columns, the registry utilizes the entity_tag_t and entity_category_t tables (with entity_type = 'skill'). This allows for unlimited flat tagging and deep hierarchical folder structures that are consistent across the entire portal.
3. Discovery API: Portal-query filters by these tags/categories to scoped skill sets for specific agent personas. Agents cache the effective catalog locally and reload it when runtime cache-management invalidation is triggered.

4.2 Progressive Disclosure Patterns

Agents should not load every executable tool into the LLM context. Instead, they should load their assigned skill/tool catalog from the portal API, cache it locally, and use one of the following progressive disclosure patterns:

Phase 5 starts with the Rust light-agent. The agent loads genai-query/getEffectiveAgentCatalog, keeps a local cache keyed by hostId + agentDefId + serviceId + envTag, ranks cached skill/tool entries with keyword and routing-field matching, and intersects the selected tool names with the live gateway tools/list result before giving schemas to the model. Execution remains gateway tools/call.

Pattern A: Meta-Tools (Dynamic Injection)

The agent is booted with only two "meta-tools" designed for discovery.

1. Local catalog search: Agent searches its cached assigned skills. The cache contains lightweight summaries and mapped tool names.
2. Schema loading: Once the agent identifies the correct tool, it loads the schema from the local catalog cache or refreshes the cache from portal-query.

Pattern B: Semantic Tool RAG (Zero-Shot Discovery)

For highly complex systems with thousands of skills:

1. Tool descriptions are embedded into a Vector Database (e.g., pgvector).
2. When the user prompts the system (e.g., "Reset my AWS password"), portal-query or the agent's local cache performs semantic search and retrieves the Top-3 most relevant JSON Schemas.
3. The agent boots with only those 3 tools in its context.

Pattern C: Multi-Agent Orchestration (Supervisor / Worker)

Hierarchy is mapped to agent teams.

1. A Supervisor Agent holds routing tools (e.g., delegate_to_finance, delegate_to_devops).
2. When delegate_to_devops is triggered, the supervisor routes to a DevOps Worker Agent, loading only the specific DevOps JSON schemas into its context.

5. Example Flow: Dynamic Loading in Action

User: "I need to provision a new database for the marketing team."

1. Turn 1: Discovery
   • Agent Context: Has a local cache of assigned skill summaries.
   • Agent Action: Searches the local cache for provision database.
2. Turn 2: High-Level Awareness
   • Local Cache Result: Returns token-efficient summaries from the portal catalog: [{"name": "aws_rds_provision", "description": "Creates AWS RDS DB"}, {"name": "mongo_atlas_create", "description": "Creates Mongo cluster"}]
   • Agent Action: Decides AWS is needed and loads the cached schema for aws_rds_provision.
3. Turn 3: Strict Execution
   • Agent Catalog: Provides the full JSON schema (requiring instance_type, storage_gb).
   • Agent Action: Understands parameters and safely executes aws_rds_provision through the gateway tools/call path.

6. Operational Benefits & Security

By centralizing skills in a database, the platform gains enterprise-grade operational capabilities:

• Dynamic Updates: API endpoints, instructions, and schemas can be updated in the database without restarting agents.
• Permission-Aware Discovery (RBAC): By linking skills to LightAPI endpoint descriptions and api_endpoint_t, portal-query can limit catalog disclosure to the current agent or tenant, while runtime gateway policy still authorizes execution.
• A/B Testing: Portal catalog metadata can route 50% of an agent's requests to skill_v1 and 50% to skill_v2 to measure prompt/tool efficacy.
• Audit Logging: Catalog disclosure and gateway execution can be logged separately, preserving a compliance trail without moving tool execution into the registry.
• Distilled Memory RAG: Following the "Hindsight" pattern, raw conversation history (agent_session_history_t) is separated from RAG-optimized memory (session_memory_t). This prevents the "noisy context" problem while maintaining a perfect audit trail.

7. LightAPI As Skill Source

API-backed skills should be generated from endpoint-level LightAPI descriptions whenever possible.

The skill registry should store skill metadata, access control, grouping, and agent-facing instructions. The LightAPI description should remain the source of truth for endpoint invocation and verification details.

Recommended flow:

1. Light-Portal creates or imports endpoint-level LightAPI descriptions.
2. API owners enrich endpoint descriptions with examples, behavior notes, result cases, and visibility.
3. Approved endpoint descriptions are published as agent skills.
4. The agent loads assigned skill summaries from portal-query and caches them locally.
5. When the agent selects a skill, it loads the relevant LightAPI disclosure level from the local cache or refreshes from portal-query.
6. Execution goes through the gateway tools/call path, preserving runtime policy and downstream authorization.

This avoids manually duplicating every API endpoint as a separate hand-written skill while still giving agents strict schemas and progressive disclosure.

8. Workflow-Backed Skills

Some skills need more than instructions and a curated tool set. A skill that must orchestrate several tools, wait for human approval, retry failed steps, run assertions, or preserve a durable audit trail should be backed by light-workflow.

The boundary should stay clear:

Workflow backing should be optional. Simple skills can stay as instructions plus tool mappings. Durable or regulated processes should link to workflow definitions and let light-workflow own execution.

Recommended storage:

1. Keep wf_definition_t.definition as the canonical workflow YAML.
2. Keep skill_t.content_markdown as the LLM-facing skill instruction body.
3. Add skill_workflow_t to link skills to workflow definitions with a role such as primary, validation, remediation, or test.
4. Treat skill_tool_t as the allowed tool set for a workflow-backed skill. Validation should flag workflow tool-call steps that are not linked to the skill.

The Portal Skill Workspace should embed a generic Workflow Editor instead of creating a skill-specific workflow runtime. The editor provides YAML editing, step preview, reference lookup, validation, and test runs. Skill authoring provides the surrounding context: skill metadata, taxonomy, allowed tools, effective prompt preview, and workflow link configuration.

9. Next Steps

1. Complete phase 3 by adding category and tag assignment to existing skill create/update forms, backed by entity_category_t and entity_tag_t with entity_type = 'skill'.
2. Save skill taxonomy through a composite skill command so the skill row and selected taxonomy associations are emitted from the same user action.
3. Move the richer authoring workspace, effective prompt preview, skill_tool_t.config formalization, workflow-backed skills, and "create skill from LightAPI/tool" flows to phase 3.5.
4. Build the generic Workflow Editor for YAML editing, parsed step preview, catalog references, validation, and workflow test runs.
5. Complete phase 4 agent assignment by improving the agent_skill_t UI, adding an Agent Definition assignment context, and adding a batch assignment composite command that emits one AgentSkillCreatedEvent per selected skill.
6. Enforce phase 4 assignment validation in command handlers and UI preflight: assigned skills must be active and must have at least one active direct skill_tool_t link. Workflow-backed skills still rely on skill_tool_t as the allowed tool set.
7. Keep live gateway tools/list runtime executability checks as a diagnostics or governance concern, not as phase 4 persistence validation.
8. Complete phase 5 for the Rust agent with the genai-query getEffectiveAgentCatalog endpoint, claim checks against host, sid, and env, local catalog caching, keyword/routing search, gateway tools/list intersection, and controller-driven cache invalidation.
9. Complete phase 6 governance for the Rust agent only: normalize sensitivity tiers to public, internal, confidential, and restricted; filter blocked tools before catalog disclosure; compare the effective catalog with gateway tools/list through /diagnostics/tools; and keep execution through gateway tools/call.
10. Enforce destructive, approval-required, and sensitivity metadata at the gateway with debug/auditInfo fields when a call is blocked. Do not use workflow audit_log_t for catalog disclosure; use auditInfo/file logging until a generic governance audit table is introduced.
11. Keep current active row plus aggregate version as the approval/version boundary until workflow-owned approval state is implemented.
12. Add publishing from LightAPI endpoint descriptions into the skill registry.
13. Migrate existing file-based skills into structured catalog payloads, keeping instructions in Markdown and converting parameters to JSON Schema.
14. Implement Pattern B (Semantic Tool RAG) after indexed catalog fields and embeddings are ready for production search.

Skill Workflow Orchestration

Status

Proposed demo design.

Executive Summary

This design describes a focused demo for agent-driven orchestration in Light-Fabric. The demo uses one agent with two skills:

1. A skill that starts a workflow which calls two REST APIs directly.
2. A skill that starts a workflow which calls the same two REST APIs through the MCP router.

Both paths solve the same business use case and return the same output. The visible difference is the execution trace:

• The REST workflow shows light-workflow invoking HTTP endpoints directly.
• The MCP workflow shows light-workflow invoking MCP tools/call, with light-gateway routing each tool call to the same backend REST APIs.

This demonstrates that skills provide agent-facing guidance and discovery, workflows provide durable orchestration, and the gateway provides the MCP data plane for tool execution.

Goals

• Show one agent selecting between two assigned skills.
• Show a workflow that orchestrates multiple REST APIs directly.
• Show a second workflow that orchestrates the same APIs through MCP tools.
• Keep the input and output contract identical across both workflows.
• Keep the demo small enough to explain in a few minutes.
• Preserve the runtime boundary: skills guide, workflows orchestrate, gateway executes MCP tool calls.

Non-Goals

• Do not benchmark REST versus MCP latency.
• Do not claim that MCP replaces REST. The demo shows two supported access patterns over the same backend capabilities.
• Do not require every skill to be workflow-backed. Simple skills can remain instructions plus allowed tools.
• Do not move MCP tool execution into the portal registry or agent catalog. Runtime tool execution stays on the gateway tools/call path.
• Do not make the demo depend on a large endpoint catalog.

Recommendation

Use two APIs, not one.

A one-API demo can show sequencing, but it does not clearly prove cross-service orchestration. Two APIs show a more realistic enterprise shape: the workflow has to collect data from one business capability and make a decision through another capability.

Use four endpoints for the base demo.

The base demo should be small enough to run repeatedly while still proving meaningful orchestration behavior.

Demo Scenario

The demo domain is personalized offer recommendation.

The agent receives a prompt such as:

Recommend an offer for customer CUST-1001.

The agent can use either skill:

• Personalized Offer via REST Workflow
• Personalized Offer via MCP Router

If the prompt does not specify REST or MCP, the demo agent should not pick a path at random. It should ask a short clarification question:

Do you want to run this through the direct REST workflow or through the MCP
router workflow?

Scripted demos can avoid the clarification by naming the path in the prompt.

Both skills start a workflow that:

1. Loads the customer profile.
2. Loads customer preferences and consent.
3. Stops if the customer has not consented.
4. Searches for eligible offers.
5. Selects the best offer.
6. Records the offer decision.
7. Returns a normalized decision payload.

APIs And Endpoints

Customer Profile API

The Customer Profile API owns customer data and preferences.

Offer Decision API

The Offer Decision API owns eligible offer lookup and decision recording.

Demo API Runtime Services

The two business APIs should be implemented as real Rust services using the light-axum framework, not as ad hoc mocks. This keeps the demo aligned with normal Light-Fabric service lifecycle behavior:

• load runtime configuration from config-server
• bind HTTP using configured server settings
• register with controller through portal-registry
• appear in the control panel service-discovery view
• support gateway service discovery by serviceId and envTag

Recommended demo apps:

The ports are config defaults only. They must be configurable through config-server values so local, Docker, Kubernetes, and shared demo environments can choose different ports without recompiling.

Both services should expose:

GET /health

The API endpoints should return deterministic demo data. A database is not required for the first demo; in-memory seed data is enough as long as the data is stable and documented. If later demos need persistence, keep it behind the same endpoint contract.

Light-Axum Bootstrap

Each demo API should follow the normal light-axum pattern: implement AxumApp, return an axum::Router, and let LightRuntimeBuilder own binding, configuration, shutdown, and controller registration.

The service should read config from the same runtime config files used by other Light-Fabric services:

startup.yml
server.yml
portal-registry.yml

Example config-server values for the Customer Profile API:

startup.host: dev.lightapi.net
startup.externalConfigDir: /var/lib/demo-customer-profile-api/config-cache

light-config-server-uri: https://config-server.lightapi.svc.cluster.local:8435

server.serviceId: com.networknt.demo.customer-profile-1.0.0
server.environment: demo
server.ip: 0.0.0.0
server.advertisedAddress: demo-customer-profile-api
server.httpPort: 8085
server.enableHttp: true
server.enableHttps: false
server.enableRegistry: true
server.startOnRegistryFailure: true

portalRegistry.portalUrl: https://controller.lightapi.svc.cluster.local:8438

Example config-server values for the Offer Decision API:

startup.host: dev.lightapi.net
startup.externalConfigDir: /var/lib/demo-offer-decision-api/config-cache

light-config-server-uri: https://config-server.lightapi.svc.cluster.local:8435

server.serviceId: com.networknt.demo.offer-decision-1.0.0
server.environment: demo
server.ip: 0.0.0.0
server.advertisedAddress: demo-offer-decision-api
server.httpPort: 8086
server.enableHttp: true
server.enableHttps: false
server.enableRegistry: true
server.startOnRegistryFailure: true

portalRegistry.portalUrl: https://controller.lightapi.svc.cluster.local:8438

server.advertisedAddress must be a reachable address, not 0.0.0.0. In Kubernetes, use the Service DNS name. In local Docker Compose, use the Compose service name. In a native VM demo, use the VM hostname or another reachable address.

Controller Registration

The services should register with controller using the runtime's portal-registry integration. The controller registration payload must include at least:

• serviceId
• envTag
• protocol
• advertised address
• port
• discovery token or portal registry token, according to environment policy

After startup, the control panel should show two registered service instances:

com.networknt.demo.customer-profile-1.0.0 / demo
com.networknt.demo.offer-decision-1.0.0 / demo

The MCP router configuration should prefer these service IDs over fixed targetHost values where service discovery is available. Fixed targetHost values are still useful for a minimal local smoke test.

Optional Advanced Endpoints

The base demo should start with four endpoints. If we later want to demonstrate more workflow shapes, add one or two optional endpoints:

Agent, Skills, And Workflows

Use one agent so the demo highlights skill selection rather than agent handoff.

The skill registry should link each skill to its workflow definition through skill_workflow_t. The workflow definition remains canonical in wf_definition_t.definition. The skill content_markdown remains agent-facing guidance, not the executable workflow source.

Execution Paths

Direct REST Workflow

User prompt
  -> Demo Orchestration Agent
  -> Personalized Offer via REST Workflow skill
  -> light-workflow
  -> Customer Profile API
  -> Offer Decision API
  -> normalized decision result

This path is useful for showing direct, durable API orchestration.

MCP Router Workflow

User prompt
  -> Demo Orchestration Agent
  -> Personalized Offer via MCP Router skill
  -> light-workflow
  -> MCP tools/call
  -> light-gateway MCP router
  -> Customer Profile API
  -> Offer Decision API
  -> normalized decision result

This path is useful for showing MCP protocol orchestration over the same backend API capabilities.

Common Workflow Contract

Both workflows should accept the same input:

{
  "customerId": "CUST-1001",
  "channel": "portal"
}

Both workflows should return the same successful output shape:

{
  "status": "APPROVED",
  "customerId": "CUST-1001",
  "selectedOfferId": "OFFER-TRAVEL-01",
  "decisionId": "DEC-1001"
}

Both workflows should return comparable business outcomes for known edge cases:

{
  "status": "NO_CONSENT",
  "customerId": "CUST-3003",
  "reason": "Customer has not consented to personalized offers."
}

{
  "status": "NO_ELIGIBLE_OFFER",
  "customerId": "CUST-2002",
  "reason": "No active offer matches the customer profile and preferences."
}

Workflow Shape

The REST and MCP workflows should have the same logical steps.

The workflow should own branching, retries, and output normalization. The agent should not manually sequence each API call after the workflow starts.

Error Handling And Retries

Business outcomes and technical failures should be treated differently.

Business outcomes are expected workflow results and should not be retried:

• NO_CONSENT
• NO_ELIGIBLE_OFFER

Technical failures should use bounded workflow retries:

Recommended transient retry status codes:

408, 429, 502, 503, 504

The POST /offer-decisions step should include an idempotency key derived from the workflow instance id and selected offer id. This prevents duplicate decisions when a retry happens after the backend processed the first request but the response was lost.

For parity, the REST and MCP workflows should use the same retry policy. In the MCP path, the gateway should preserve enough error detail for the workflow trace to show the tool name, mapped backend endpoint, status code, and correlation id.

MCP Tool Mapping

The MCP workflow should use a small, explicit tool set.

The MCP tool input schemas should be normalized JSON objects. The gateway router maps those objects to path parameters, query parameters, or request bodies for the backend REST APIs.

The MCP skill should list these tools in skill_tool_t as its allowed runtime tool set. Workflow validation should flag an MCP tool-call step if it references a tool that is not linked to the skill.

Gateway Tool Configuration Example

Current gateway HTTP tool execution maps GET arguments to query parameters and sends non-GET arguments as JSON request bodies. To support endpoint shapes such as GET /customers/{customerId} without changing the backend API, the demo should add or configure explicit path-template substitution before the request is sent.

Recommended minimal mapping shape:

mcp-router.tools:
  - name: customer_get_profile
    description: Get a customer profile by id.
    protocol: http
    serviceId: com.networknt.demo.customer-profile-1.0.0
    envTag: demo
    path: /customers/{customerId}
    method: GET
    apiType: http
    inputSchema:
      type: object
      required:
        - customerId
      properties:
        customerId:
          type: string
    toolMetadata:
      pathParams:
        - customerId

With this mapping, the MCP tool call:

{
  "name": "customer_get_profile",
  "arguments": {
    "customerId": "CUST-1001"
  }
}

should be routed to:

GET /customers/CUST-1001

The path parameter should not also be appended as a query parameter. Arguments not listed under pathParams can still be appended as query parameters for GET requests or sent as JSON body fields for POST requests.

Skill Content Markdown Guidance

The skill content_markdown should explain when and how the agent should use the skill. It should not duplicate the workflow definition or the full API contract.

Example REST skill content:

## Purpose
Use this skill when the user asks for a personalized offer decision through the
direct REST workflow.

## Inputs
- customerId: customer identifier, such as CUST-1001
- channel: request channel, default portal

## Behavior
- Start workflow personalized-offer-rest-v1.
- Return the workflow result as the answer.
- Do not manually call offer APIs outside the workflow.
- If the user does not specify REST or MCP, ask which execution path they want.

Example MCP skill content:

## Purpose
Use this skill when the user asks to demonstrate MCP router orchestration for a
personalized offer decision.

## Inputs
- customerId: customer identifier, such as CUST-1001
- channel: request channel, default portal

## Behavior
- Start workflow personalized-offer-mcp-v1.
- The workflow will call MCP tools through the gateway.
- Return the workflow result as the answer.
- If the user does not specify REST or MCP, ask which execution path they want.

Structured execution metadata belongs in registry rows and workflow definitions, not only in markdown. The markdown is the LLM-facing explanation.

Output Normalization

The workflows should not pass raw endpoint responses directly to the agent. They should normalize backend responses into a stable business result.

Example raw POST /offer-decisions response:

{
  "decisionId": "DEC-1001",
  "customerId": "CUST-1001",
  "offerId": "OFFER-TRAVEL-01",
  "decision": "approved",
  "createdAt": "2026-05-25T14:12:00Z",
  "auditRef": "AUD-7788"
}

Normalized workflow output:

{
  "status": "APPROVED",
  "customerId": "CUST-1001",
  "selectedOfferId": "OFFER-TRAVEL-01",
  "decisionId": "DEC-1001"
}

The workflow should own this transformation so the REST and MCP variants produce identical final results even if their intermediate transport envelopes are different.

Demo Data

Use deterministic seed data so the demo is repeatable.

Seed offers:

Demo Script

Run the REST workflow path first:

Use the REST workflow skill to recommend an offer for CUST-1001.

Expected observation:

• The agent selects Personalized Offer via REST Workflow.
• The workflow trace shows direct HTTP calls to the Customer Profile API and Offer Decision API.
• The final response contains status=APPROVED and a decision id.

Run the MCP workflow path second:

Use the MCP router skill to recommend an offer for CUST-1001.

Expected observation:

• The agent selects Personalized Offer via MCP Router.
• The workflow trace shows MCP tools/call invocations.
• The gateway trace shows those tool calls routed to the same backend REST endpoints.
• The final response uses the same output shape as the REST workflow.

Then run one edge case:

Use either skill to recommend an offer for CUST-3003.

Expected observation:

• The workflow stops after the consent check.
• No offer decision is recorded.
• The result is NO_CONSENT.

Run one ambiguity case:

Recommend an offer for CUST-1001.

Expected observation:

• The agent asks whether to use the direct REST workflow or the MCP router workflow.
• After the user chooses, the agent starts the selected workflow.

Run one technical failure case:

Use the MCP router skill to recommend an offer for CUST-1001 while the Offer
Decision API returns one transient 503.

Expected observation:

• The workflow retries the failed tool-call step.
• The gateway trace records the failed offer_record_decision call and the successful retry.
• The final response still uses the normalized APPROVED output shape.

Portal Authoring Flow

The portal should make the demo visible from the existing GenAI and workflow surfaces:

1. Create or import the two REST APIs and four endpoint descriptions.
2. Implement the two APIs as light-axum services.
3. Add config-server values for both API services.
4. Start both services and verify controller registration.
5. Publish MCP router tools for the same four endpoints.
6. Create personalized-offer-rest-v1 in the workflow catalog.
7. Create personalized-offer-mcp-v1 in the workflow catalog.
8. Create the two skills in the skill registry.
9. Link each skill to its primary workflow through skill_workflow_t.
10. Link the MCP skill to its allowed tool set through skill_tool_t.
11. Assign both skills to Demo Orchestration Agent.
12. Use Skill Workspace preview and test panels to validate the effective prompt, workflow link, allowed tools, and sample test input.

Validation Rules

The authoring experience should validate the following before the demo is considered complete:

• Each skill has exactly one primary workflow link.
• The REST workflow does not require MCP tools.
• The MCP workflow references only MCP tools linked through skill_tool_t.
• Both workflows declare the same input schema.
• Both workflows declare the same normalized output shape.
• The four backend endpoint descriptions are active.
• Both demo API services load config from config-server.
• Both demo API services register with controller and appear in the control panel service-discovery view.
• The MCP router tools/list result includes the four expected tool names.
• MCP router tools resolve the demo APIs by serviceId and envTag in the service-discovery environment.
• MCP path-parameter mappings are validated before the workflow test run.
• POST /offer-decisions includes an idempotency key for retry safety.
• Test runs for CUST-1001, CUST-2002, and CUST-3003 produce the expected outcomes.

Observability

The demo should show three different traces:

1. Agent trace: which skill the agent selected and what workflow it started.
2. Workflow trace: step order, branches, retries, and final output.
3. Gateway trace: MCP tool name, mapped backend endpoint, status, duration, and correlation id for the MCP path.

Use the same correlation id across the agent request, workflow instance, and gateway calls where possible. This makes the REST and MCP execution paths easy to compare.

Security And Authorization

Authorization should be enforced at each layer:

• The agent can discover only assigned skills.
• The workflow can start only definitions visible to the authenticated caller or service identity.
• The MCP skill can expose only tools linked to the skill and allowed for the agent.
• The gateway still performs runtime MCP access checks before executing tools/call.
• Backend REST APIs continue to enforce their own authorization policies.

The skill registry is not a runtime bypass. It narrows discovery and guidance, while the workflow and gateway remain responsible for execution-time controls.

Context And Auth Propagation

The demo should explicitly show that caller context is preserved.

For direct REST workflow steps:

1. The workflow start request records the initiating user, host, tenant, correlation id, and authorization context.
2. The workflow executor builds outbound REST calls with the correct caller context. If the original bearer token is safe to forward, it can be passed through. Otherwise, the workflow service should use a service token with on-behalf-of metadata that preserves the initiating subject.
3. Backend APIs enforce their normal authorization policies.

For MCP workflow steps:

1. light-workflow calls the gateway MCP endpoint with the same correlation, tenant, locale, and authorization context.
2. light-gateway validates the MCP request and runtime tool authorization.
3. The MCP router forwards the allowed caller headers to the backend REST API while regenerating transport-specific headers such as Host, Content-Length, and connection management headers.
4. Backend APIs see the same business identity context they would see on the direct REST path.

The trace should show this propagation without exposing sensitive token values.

Acceptance Criteria

• One demo agent has both skills assigned.
• The REST skill starts personalized-offer-rest-v1.
• The MCP skill starts personalized-offer-mcp-v1.
• Both workflows accept the same input JSON.
• Both workflows return the same normalized output shape.
• The REST workflow trace shows direct REST calls to two APIs.
• The MCP workflow trace shows MCP tools/call routed through the gateway to the same two APIs.
• The two APIs run as light-axum services with config-server supplied HTTP ports.
• The two APIs register with controller and are visible in the control panel service-discovery view.
• The demo succeeds for CUST-1001.
• The demo returns controlled business outcomes for CUST-2002 and CUST-3003.
• Ambiguous user prompts trigger a clarification question instead of random skill selection.
• A transient 503 from the Offer Decision API is retried and appears in the workflow trace.
• The MCP path preserves caller context through workflow, gateway, and backend REST calls.

Related Designs

• Agentic Workflow
• Workflow Client Architecture
• Centralized Skills
• LightAPI Description
• MCP Router

Hindsight Memory

Hindsight Memory is the core memory system for light-rs, designed to move beyond simple chat logs. Instead of just remembering what was said, the agent learns and forms mental models over time.

This design is strongly inspired by the paper Hindsight is 20/20: Building Agent Memory that Retains, Recalls, and Reflects and extends it with multi-tenant support.

1. Core Concepts

Hindsight memory organizes information into three distinct "Pathway" types:

1. World Facts: Objective truths about the environment (e.g., "The production server is in US-East-1").
2. Experiences: The agent's own history of actions and results (e.g., "I tried to deploy to US-East-1 and it failed due to a timeout").
3. Mental Models: Synthesized understandings formed by reflecting on facts and experiences (e.g., "Deployments to US-East-1 are unstable during peak hours").

2. The Three Operations

Interaction with the memory system is standardized into three primary operations:

Retain (Storage)

The retain operation ingests information. Behind the scenes, the system:

• Extracts entities and relationships.
• Normalizes time and temporal data.
• Stores the data in agent_memory_unit_t.

Recall (Retrieval)

The recall operation retrieves relevant context using a hybrid strategy:

• Semantic: Vector similarity using the hnsw index.
• Graph: Following links in agent_memory_link_t (causes, enables, prevents).
• Temporal: Time-series filtering.

Reflect (Synthesis)

The reflect operation performs "deep thinking." It analyzes existing memories to generate new insights, which are stored in agent_memory_reflection_t.

3. Database Architecture

The Hindsight system is fully integrated into the portal's multi-tenant schema:

4. Privacy & Multi-Tenancy

Isolation is managed at the Bank level using three scoping tiers:

1. Global Host Bank (user_id IS NULL, agent_def_id IS NULL):
   • Knowledge shared across all users and all agents within a specific host_id.
   • Ideal for organization-wide SOPs, common facts, and shared documentation.
2. Shared Agent Bank (user_id IS NULL, agent_def_id IS NOT NULL):
   • Knowledge shared by all users interacting with a specific agent type.
   • Used for maintaining a consistent agent "Persona" or specialized domain expertise.
3. Private User Bank (user_id IS NOT NULL):
   • Knowledge unique to a specific user.
   • Can be scoped further by agent_def_id to provide user-specific memory within a particular agent persona.
   • Used for personal preferences, private history, and individualized learning.

5. Implementation Guide

To implement a "Learning Agent," follow this sequence in your application logic:

1. Ingestion: After every tool call or user interaction, call retain to update the bank.
2. Context Loading: Before calling the LLM, call recall to fetch the most relevant 3-5 memories for the current prompt.
3. Scheduled Reflection: Run the reflect operation during idle time to compress raw experiences into high-level mental models.

Fine-Grained Authorization

The following is the raw material collected when I chat with AI about migrating the light-4j fine-grained authorization to light-rs to secure light-agent and light-gateway.

The information needs to be organized and documented into a design document for light-rs fine-grained authorization.

Question: We have a Java implementation of fine-grained authorization that we want to migrate to light-rs. In our java implementation, we have a middleware handler to verify the custom claims like role, group, attribute etc in the jwt token against endpoint specific rules defined in database and cached at the service. How should we handle the same requirement in rust?

Response:

In Rust, bridging the gap between dynamic, database-driven rules and high-performance web requests is a well-solved problem. If you are coming from Java, the architecture translates very cleanly, but takes advantage of Rust's async runtime and thread-safe concurrency primitives.

To handle fine-grained authorization (Attribute-Based Access Control / ABAC or Role-Based Access Control / RBAC) where rules are cached locally but backed by a database, you have two primary paths in Rust:

1. The Custom Middleware Approach (Closest to your current Java implementation)
2. The Policy Engine Approach (Using an industry-standard Rust authorization crate)

Here is how you handle this requirement idiomatically in Rust, assuming you are using Axum (the current standard web framework in Rust).

Approach 1: Custom Middleware with Async Caching

In Java, you likely used something like Guava or Caffeine for your local cache. In Rust, the exact equivalent for high-performance, concurrent, async-aware caching is the moka crate.

Here is the architectural blueprint:

1. Define your custom claims using serde.
2. Setup a shared Application State holding your Database connection pool (e.g., sqlx) and your local Cache (moka).
3. Create an Axum Middleware to intercept the request, parse the JWT, consult the cache based on the route, and authorize the request.

1. Dependencies (Cargo.toml)

axum = "0.7"
jsonwebtoken = "9.0"
moka = { version = "0.12", features = ["future"] } # Async cache (Rust's Caffeine)
sqlx = { version = "0.7", features = ["postgres", "runtime-tokio"] }
serde = { version = "1.0", features = ["derive"] }

2. Defining Claims and State

#![allow(unused)]
fn main() {
use axum::{extract::State, http::Request, middleware::Next, response::Response};
use moka::future::Cache;
use serde::{Deserialize, Serialize};
use sqlx::PgPool;
use std::sync::Arc;

// 1. Define your custom JWT claims
#[derive(Debug, Serialize, Deserialize, Clone)]
struct CustomClaims {
    sub: String,
    roles: Vec<String>,
    groups: Vec<String>,
    attributes: std::collections::HashMap<String, String>,
    exp: usize,
}

// 2. Define the Endpoint Rule (what you fetch from DB)
#[derive(Clone)]
struct EndpointRule {
    required_roles: Vec<String>,
    // add required_groups, attributes, etc.
}

// 3. Define the Application State to share across your app
struct AppState {
    db: PgPool,
    // Cache keyed by String (e.g., "GET:/api/data") returning an EndpointRule
    rule_cache: Cache<String, EndpointRule>,
}
}

3. The Authorization Middleware

In Axum, middleware is written as an asynchronous function that takes the request, does some work, and either rejects it or passes it to the Next handler.

#![allow(unused)]
fn main() {
use axum::http::StatusCode;
use axum::response::IntoResponse;

async fn fine_grained_authz_middleware(
    State(state): State<Arc<AppState>>,
    req: Request<axum::body::Body>,
    next: Next,
) -> Result<Response, StatusCode> {
    
    // 1. Extract and decode the JWT from Authorization header
    let auth_header = req.headers().get("Authorization").and_then(|h| h.to_str().ok());
    let claims = decode_jwt(auth_header).ok_or(StatusCode::UNAUTHORIZED)?;

    // 2. Identify the endpoint being accessed (e.g., "GET:/api/users/123")
    // Note: In practice, use req.extensions() to get the matched generic route template
    // rather than the raw URI so "/api/users/123" matches "/api/users/{id}"
    let endpoint_key = format!("{}:{}", req.method(), req.uri().path());

    // 3. Check Cache or Fallback to DB
    let rule = match state.rule_cache.get(&endpoint_key).await {
        Some(cached_rule) => cached_rule,
        None => {
            // Cache miss: Fetch from database
            let db_rule = fetch_rule_from_db(&state.db, &endpoint_key)
                .await
                .map_err(|_| StatusCode::INTERNAL_SERVER_ERROR)?;
            
            // Populate cache
            state.rule_cache.insert(endpoint_key, db_rule.clone()).await;
            db_rule
        }
    };

    // 4. Execute Fine-Grained Authorization Logic
    let is_authorized = rule.required_roles.iter().any(|role| claims.roles.contains(role));
    // ... check groups, evaluate custom attribute expressions, etc.

    if !is_authorized {
        return Err(StatusCode::FORBIDDEN);
    }

    // 5. Pass to the actual route handler!
    Ok(next.run(req).await)
}

// Dummy helper functions to make the example compile mentally
fn decode_jwt(_header: Option<&str>) -> Option<CustomClaims> { /* ... */ unimplemented!() }
async fn fetch_rule_from_db(_db: &PgPool, _key: &str) -> Result<EndpointRule, ()> { /* ... */ unimplemented!() }
}

4. Wiring it up

use axum::{routing::get, Router};

#[tokio::main]
async fn main() {
    let state = Arc::new(AppState {
        db: PgPool::connect("postgres://...").await.unwrap(),
        rule_cache: Cache::builder()
            .max_capacity(10_000)
            .time_to_live(std::time::Duration::from_secs(300)) // 5 minute TTL
            .build(),
    });

    let app = Router::new()
        .route("/api/secure-data", get(|| async { "Secret Data" }))
        // Apply the middleware to all routes above this line
        .route_layer(axum::middleware::from_fn_with_state(state.clone(), fine_grained_authz_middleware))
        .with_state(state);

    let listener = tokio::net::TcpListener::bind("0.0.0.0:3000").await.unwrap();
    axum::serve(listener, app).await.unwrap();
}

Approach 2: Using a Dedicated Policy Engine (Recommended for complex rules)

If your endpoint-specific rules are highly complex (e.g., "User must be in Group X AND have Attribute Y = 'finance', UNLESS Role is 'Admin'"), writing that evaluation logic manually in Rust gets messy.

Instead of writing custom evaluation logic, the Rust ecosystem heavily relies on external Policy Engines for ABAC/RBAC. The two leaders are:

1. AWS Cedar (cedar-policy) - Highly Recommended

Developed by Amazon Web Services in Rust, Cedar is a blazing-fast language for defining permissions.

• You store your Cedar policies in your database as text.
• Your Rust middleware fetches the Cedar policy string from the DB, compiles it (and caches the compiled policy using moka).
• You pass the JWT CustomClaims into the Cedar engine as a context entity.
• Cedar evaluates the claims against the policy in microseconds.

2. Casbin (casbin)

Casbin is a very popular authorization library that exists in Java, Go, and Rust.

• It supports ACL, RBAC, and ABAC.
• It has native adapters for sqlx (Postgres/MySQL). You don't even need to write the caching logic yourself; casbin-rs handles reading the rules from the database and keeping them cached in memory automatically.

Summary

• For simple Role/Group matching: Stick to the Custom Middleware approach using moka for async caching and axum::middleware to intercept requests. It is functionally identical to your Java approach but extremely fast.
• For complex Attribute evaluation: Use your middleware to parse the JWT, but delegate the actual rule evaluation to cedar-policy or casbin.

Question: Could you please provide some examples for cedar-policy and casbin? For example, what is the format in database? In our system, we are using a yaml rule engine to evaluate the fine-grained authorization. We create some rules users can choose and they can also create their own rules if necessary.

Response:

Transitioning from a custom YAML rule engine to an industry-standard policy engine is a fantastic move. Both AWS Cedar and Casbin are designed precisely for this kind of "user-defined fine-grained rules" requirement, but they take very different approaches to how rules are written and stored.

Here is a breakdown of how both engines work, what their database format looks like, and how you map your JWT claims to them in Rust.

1. AWS Cedar (cedar-policy) - Best for Complex/Custom Rules

Cedar uses a custom, highly readable Domain Specific Language (DSL). It is specifically built to evaluate ABAC (Attribute-Based Access Control) using contextual data like JWT claims.

The Format (In the Database)

In your database, you do not need complex tables. You simply store the Cedar policies as plain text strings in a standard TEXT or VARCHAR column.

If a user wants to create a custom rule saying, "Allow access if the user's JWT has the 'finance' group and a clearance level greater than 3," the Cedar policy stored in the DB looks like this:

// Database column: policy_text
permit (
    principal,
    action == Action::"read_data",
    resource == Resource::"secure_endpoint"
)
when {
    context.jwt.groups contains "finance" &&
    context.jwt.attributes.clearance_level > 3
};

For "predefined rules that users can choose," Cedar has Policy Templates. You store the template once, and users just link their parameters to it.

// Template: "Require specific group"
permit(principal, action, resource)
when { context.jwt.groups contains ?required_group };

How you execute it in Rust

When a request comes in, you fetch the relevant Cedar text strings from your database, pass in the JWT claims as the Context, and let Cedar evaluate it.

#![allow(unused)]
fn main() {
use cedar_policy::{Authorizer, Context, Decision, Entities, PolicySet, Request};
use serde_json::json;
use std::str::FromStr;

fn evaluate_cedar_rule(db_policy_text: &str, jwt_claims: &serde_json::Value) {
    // 1. Parse the text policy from the database
    let policies = PolicySet::from_str(db_policy_text).expect("Invalid policy format");

    // 2. Map your JWT claims directly into the Cedar "Context" using JSON
    let context_json = json!({
        "jwt": jwt_claims
    });
    let context = Context::from_json_value(context_json, None).unwrap();

    // 3. Create the evaluation request
    let request = Request::new(
        Some("User::\"Alice\"".parse().unwrap()), 
        Some("Action::\"read_data\"".parse().unwrap()), 
        Some("Resource::\"secure_endpoint\"".parse().unwrap()), 
        context,
        None,
    ).unwrap();

    // 4. Evaluate
    let authorizer = Authorizer::new();
    let entities = Entities::empty(); // Used if fetching hierarchical data
    let answer = authorizer.is_authorized(&request, &policies, &entities);

    if answer.decision() == Decision::Allow {
        println!("Access Granted!");
    } else {
        println!("Access Denied. Failed policies: {:?}", answer.diagnostics().errors());
    }
}
}

2. Casbin (casbin-rs) - Best for Tabular/Database-Native Rules

Casbin works fundamentally differently. It splits authorization into two parts: the Model (a config file defining the structure of your rules) and the Policies/Rules (the actual data stored in the database).

The Format (In the Database)

Casbin doesn't store a DSL string. Instead, it natively connects to your database using an adapter (like sqlx-adapter) and creates a table usually called casbin_rule.

The table structure looks exactly like a CSV file, with columns: ptype, v0, v1, v2, v3, v4, v5.

If a user selects a predefined rule to allow the finance_admin role to read /api/data, Casbin inserts a row into your database like this:

If a user writes a custom ABAC rule using a UI (e.g., clearance > 3), Casbin can store the evaluation expression as a string in one of the columns (evaluated internally via the rhai scripting language):

How you execute it in Rust

To make Casbin evaluate JWT attributes dynamically, you define a model.conf file that tells Casbin to evaluate (eval) the string stored in the database.

The model.conf File:

[request_definition]
r = sub, obj, act

[policy_definition]
p = sub_rule, obj, act

[policy_effect]
e = some(where (p.eft == allow))

[matchers]
# This matcher says: check if the object and action match, 
# AND evaluate the ABAC rule stored in the database (p.sub_rule) against the request subject (r.sub)
m = r.obj == p.obj && r.act == p.act && eval(p.sub_rule) 

The Rust Code:

#![allow(unused)]
fn main() {
use casbin::{CoreApi, Enforcer, DefaultModel};
use sqlx_adapter::SqlxAdapter;
use std::collections::HashMap;

// A struct representing your JWT Claims
#[derive(Clone)]
struct JwtClaims {
    groups: Vec<String>,
    clearance: i32,
}

async fn evaluate_casbin() {
    // 1. Connect to DB. The adapter automatically fetches the rules from the `casbin_rule` table.
    let adapter = SqlxAdapter::new("postgres://user:pass@localhost/db", 8).await.unwrap();
    let mut enforcer = Enforcer::new("model.conf", adapter).await.unwrap();

    // 2. Parse the JWT for the incoming request
    let claims = JwtClaims {
        groups: vec!["finance".to_string()],
        clearance: 5,
    };

    // 3. Casbin in Rust uses `rhai` under the hood for dynamic object evaluation.
    // You map your JWT fields into a format the engine understands.
    let mut sub_map = HashMap::new();
    sub_map.insert("groups", claims.groups);
    sub_map.insert("clearance", claims.clearance);

    // 4. Enforce the rules against the DB
    // Request is: Subject (JWT Claims Map), Object (/api/data), Action (read)
    if enforcer.enforce((sub_map, "/api/data", "read")).unwrap() {
        println!("Access Granted!");
    } else {
        println!("Access Denied!");
    }
}
}

Which one maps better to your YAML Rule Engine?

AWS Cedar is highly recommended for your use case.

Because you currently use a YAML rule engine where users define complex logical rules, your users are already accustomed to defining logical expressions.

1. Translation: It is very easy to write a script that takes your existing YAML definitions and converts them into Cedar text policies.
2. Safety: Cedar is statically typed and formally verified. If a user writes an invalid custom rule, Cedar will fail to parse it instantly and give you a helpful error message to show in your UI. Casbin's eval() logic can sometimes be brittle at runtime if the user types bad syntax.
3. Database Schema: With Cedar, you control your database schema. You just add a policy_text column to your existing "Rules" table. Casbin requires taking over a table (casbin_rule) to map to its strict CSV-like format.

Question: In our current implementation, we define all the persmissions and filters from UI and save the permissions and picked up rule in database. During server startup, it load everything locally in yaml format like the following. One of the pros is that our technical team write the rules, and the user or api owner just define the roles, groups, positions, attributes for the endpoint. The rule will be executed locally on the target server without going to the database so the performance is very good. If any permission changed for the target server, we can trigger a config reload from controller to ask the server to reload the config/permission. I am not sure if we should replace this implementation with Cedar. One of the feature we have is the column and row filter and I don't think Cedar support it. What do you think?

rule.endpointRules:
  echo@call:
    req-acc:
    - allow-role-based-access-control.lightapi.net
    permission:
      roles: mcp-reader
  /v1/pets@get:
    req-acc:
    - allow-role-based-access-control.lightapi.net
    permission:
      roles: host-admin
  /v1/accounts@get:
    req-acc:
    - allow-role-based-access-control.lightapi.net
    res-fil:
    - response-column-filter.lightapi.net
    - response-row-filter.lightapi.net
    permission:
      col:
        role:
          teller: '["accountNo","userId","accountType","firstName","lastName"]'
          account-manager: '["accountNo","userId","accountType","firstName","lastName","status"]'
      row:
        role:
          teller:
          - colName: accountType
            colValue: C
            operator: =
      roles: account-manager teller

Response:

You have excellent architectural instincts. You are absolutely right to hesitate, and your concern about column and row filtering is the exact reason you probably should not replace your current system with Cedar.

Your current design is actually highly sophisticated. Let’s break down why your current implementation is so strong, why Cedar would struggle with your specific requirements, and how you should idiomatically build your current design in Rust.

Why Cedar is NOT a drop-in replacement for your system

AWS Cedar (and most standard policy engines like Casbin or OPA) are designed as Binary Decision Engines. You give them a Request, and they return an Allow or Deny.

The Missing Feature: Data Filtering (Masking) Your system handles two fundamentally different concerns in one elegant YAML file:

1. Access Control (req-acc): Can the user access the /v1/accounts endpoint? (Cedar does this perfectly).
2. Data Filtering (res-fil): Which rows and columns can the user see in the response? (Cedar does not do this natively).

If you forced Cedar to do column filtering, you would have to misuse its "Annotations" feature to attach custom metadata to policies, read the output, and then write a custom Rust engine to parse that metadata and filter the JSON anyway. You would essentially be rebuilding your existing system, just with Cedar awkwardly wedged in the middle.

Strengths of your current architecture

What you have built is essentially a custom API Gateway / Sidecar Data Masking Engine.

1. Performance: Loading rules into memory at startup means zero network latency. (Matches Cedar).
2. Hot Reloading: Fetching updates via a controller is standard cloud-native practice. (Matches Cedar).
3. Separation of Concerns: Tech team writes the underlying engine logic (allow-role-based-access-control), while API owners just write YAML configs. (Matches Cedar’s Policy Templates).
4. Row/Column filtering: Natively understood by your engine. (Far exceeds Cedar).

Verdict: Do not switch to Cedar. Your current YAML-based, locally cached evaluation engine is a perfect fit for your business requirements.

How to implement your architecture in Rust

Since you are migrating to or building in Rust, your current Java-based architecture translates beautifully. In fact, Rust will make this system significantly faster and more memory-efficient.

Here is how you replicate your exact Java architecture—including the hot-reloading and filtering—in Rust.

1. Hot-Reloading using arc-swap

In Java, hot-reloading configuration safely across threads can be tricky. In Rust, the industry standard for "read-heavy, occasionally-updated" memory structures is the arc-swap crate. It allows your web server to read the YAML rules lock-free at millions of requests per second, while your controller can swap out the rules in the background instantly.

#![allow(unused)]
fn main() {
use arc_swap::ArcSwap;
use serde::Deserialize;
use std::sync::Arc;
use std::collections::HashMap;

// 1. Map your YAML exactly to Rust Structs
#[derive(Deserialize, Debug, Clone)]
struct EndpointRule {
    #[serde(rename = "req-acc")]
    req_acc: Option<Vec<String>>,
    #[serde(rename = "res-fil")]
    res_fil: Option<Vec<String>>,
    permission: PermissionConfig,
}

#[derive(Deserialize, Debug, Clone)]
struct PermissionConfig {
    roles: String,
    col: Option<HashMap<String, HashMap<String, String>>>, // Map for roles to column JSON strings
}

// 2. Wrap your entire config in an ArcSwap
lazy_static::lazy_static! {
    static ref CONFIG: ArcSwap<HashMap<String, EndpointRule>> = ArcSwap::from_pointee(HashMap::new());
}

// 3. Background task to listen to the Controller and Hot-Reload
async fn reload_config_from_controller(new_yaml_str: &str) {
    let new_config: HashMap<String, EndpointRule> = serde_yaml::from_str(new_yaml_str).unwrap();
    // Swaps the pointer atomically. 
    // All new requests see the new rules instantly. Old requests finish using the old rules.
    CONFIG.store(Arc::new(new_config));
}
}

2. The Request Access (req-acc) Middleware

You would write an Axum middleware that intercepts the request, looks up the current endpoint in the arc-swap configuration, checks the JWT roles against permission.roles, and rejects the request if it fails.

#![allow(unused)]
fn main() {
// Inside your Axum middleware
let current_config = CONFIG.load();
if let Some(rule) = current_config.get("/v1/accounts@get") {
    let required_roles: Vec<&str> = rule.permission.roles.split_whitespace().collect();
    if !user_roles.iter().any(|r| required_roles.contains(&r.as_str())) {
        return Err(StatusCode::FORBIDDEN); // req-acc fails
    }
}
}

3. The Response Filtering (res-fil) Middleware

This is where Rust shines. Because Axum and Actix allow you to intercept the response body after the handler completes but before it goes to the user, you can apply your column filtering dynamically.

Using serde_json, you can strip out columns that the user isn't allowed to see based on the col mapping in your YAML.

#![allow(unused)]
fn main() {
use serde_json::Value;

fn apply_column_filter(mut response_json: Value, allowed_columns_json: &str) -> Value {
    // 1. Parse the allowed columns from the YAML string (e.g., '["accountNo","firstName"]')
    let allowed_cols: Vec<String> = serde_json::from_str(allowed_columns_json).unwrap();

    // 2. Filter the JSON object
    if let Value::Object(ref mut map) = response_json {
        // Retain only the keys that are in the allowed_cols list
        map.retain(|key, _| allowed_cols.contains(key));
    }
    
    response_json
}
}

Summary

Keep your current system!

1. The YAML approach is great. It acts as a perfect declarative contract between your API owners and your technical rules engine.
2. Cedar is the wrong tool for Data Masking. Cedar is for strict Allow/Deny decisions, not mutating response bodies or filtering data.
3. Rust will supercharge this. By using serde_yaml to parse your config, arc-swap for lock-free hot-reloading, and serde_json for column masking inside an Axum middleware, you will get a system that does exactly what your Java system does, but with significantly less memory overhead and higher throughput.

Agent Engine Pattern

The Agent Engine Pattern is the architectural standard for building industrial-grade, metadata-driven AI platforms within the Light-Fabric ecosystem.

In this model, the Rust Runtime acts as a high-performance Orchestrator, while the Application Logic resides in externalized metadata (JSON/YAML) and the Hindsight Memory database.

1. Why the Metadata-Driven Approach?

• Separation of Concerns: Complex platform logic (security, retries, database connectivity, LLM integration) is implemented once in Rust. Business logic—defining agent personas, goals, and steps—is "programmed" via JSON or Database records.
• Hot-Reloading: Using the arc-swap crate and YAML-based rule engines, agent personas, model parameters, and tool access can be updated in real-time without a server restart.
• Elastic Scalability: Deploy a single, generic light-agent binary. At runtime, it specializes into a "Researcher," "Auditor," or "Support Specialist" based on the workflow_id or agent_id it retrieves from the registry.
• High Performance: Rust's asynchronous tokio runtime allows a single engine instance to manage thousands of concurrent agentic sessions with minimal memory overhead.

2. The Core Architecture: Engine vs. Content

To function as a generic interpreter, the Light-Fabric Engine relies on four primary components:

A. The Tool & Skill Registry (The "Hands")

The engine maps string identifiers in the workflow JSON (e.g., "call": "get_customer_data") to executable code or remote MCP tools.

• Implementation: Uses a ToolRegistry with trait objects (Box<dyn Tool>) or dynamic dispatch to MCP (Model Context Protocol) servers.
• Logic: When the LLM requests a tool call, the engine verifies permissions via Fine-Grained Authorization, executes the tool, and feeds the result back into the context.

B. Hindsight State Manager (The "Memory")

Unlike simple session storage, the state manager persists every step of the agentic interaction into biomimetic memory banks.

• Implementation: Every "turn" in the conversation is saved as a unit_t in the Hindsight database.
• Benefit: Provides fault tolerance (resuming from a crashed step) and "Recall" capabilities, allowing agents to remember past interactions across different sessions.

C. Prompt Templating (The "Mind")

System prompts and instructions are stored as templates rather than hardcoded strings.

• Implementation: Uses the tera or rinja engines for high-performance string interpolation.
• Example: "You are a {{agent_role}}. Your current objective is to {{agent_goal}}."
• Rust Logic: The engine merges runtime context (user input, memory recall, tool results) into the template before calling the LLM.

D. Policy Engine (The "Shield")

Before any tool execution or data retrieval, the engine consults the Light-Rule middleware.

• Logic: Ensures the agent has the authority to access specific data or execute specific functions, preventing "prompt injection" from leading to unauthorized actions.

3. Conceptual Implementation in Rust

The AgentEngine in Light-Fabric follows a non-blocking, async loop:

#![allow(unused)]
fn main() {
pub struct AgentEngine {
    registry: Arc<ToolRegistry>,
    memory: Arc<HindsightClient>,
    rules: Arc<RuleEngine>,
}

impl AgentEngine {
    pub async fn execute_step(&self, session_id: Uuid, task: Task) -> anyhow::Result<()> {
        // 1. Fetch current context from Hindsight Memory
        let mut context = self.memory.get_context(session_id).await?;

        // 2. Resolve Task Type (Agentic vs. Tool Call)
        match task {
            Task::LlmCall { agent_id, prompt_template } => {
                // Render prompt with Tera
                let prompt = self.render_prompt(prompt_template, &context)?;
                
                // Call LLM Provider
                let response = self.llm_provider.chat(prompt, &context).await?;
                
                // Retain turn in Hindsight
                self.memory.retain_turn(session_id, response).await?;
            },
            Task::ToolCall { tool_name, params } => {
                // 3. Enforce Fine-Grained Authorization
                if self.rules.authorize(session_id, &tool_name).await? {
                    let result = self.registry.call(&tool_name, params).await?;
                    context.add_result(tool_name, result);
                }
            }
        }

        // 4. Update Session State
        self.memory.checkpoint(session_id, context).await
    }
}
}

4. Operational Challenges & Solutions

1. Tool Versioning: As the platform evolves, tools may change. Light-Fabric handles this by versioning tool definitions in the Registry, ensuring old workflows remain compatible with the tools they were designed for.
2. Safe Execution: For dynamic "scripts" defined in metadata, Light-Fabric utilizes WebAssembly (WASM) runtimes to provide a high-performance, secure sandbox that is superior to traditional container-based isolation.
3. Observability: Because the engine is generic, tracing is built into the light-runtime. Every step generates OpenTelemetry traces, allowing developers to visualize the "thought process" and execution path of any agent in real-time.

The Recommendation

Light-Fabric adopts this "Engine-first" philosophy to ensure the platform remains sustainable. By treating the Agentic Workflow as data and the Rust Runtime as the interpreter, we achieve the perfect balance of extreme performance and business flexibility.

Database Design

The Light-Fabric utilizes a robust PostgreSQL schema to manage the entire lifecycle of agentic workflows, skills, and the biomimetic Hindsight memory system. The schema is organized into four logical layers:

1. Workflow Engine

These tables manage the definition and execution of long-running agentic workflows.

wf_definition_t

Stores the Agentic Workflow DSL (YAML) that defines the high-level orchestration logic.

process_info_t & task_info_t

Manage the runtime state of workflow instances (processes) and individual steps (tasks). They include input_data, context_data, and error_info to provide a resilient "scratchpad" for intermediate variables.

worklist_t & worklist_asst_t

Manage task assignments and visibility for human-in-the-loop interactions.

2. Agentic Core (The "Brain & Skills")

These tables define the identity, expertise, and capabilities of individual agents.

agent_definition_t

Defines the agent's persona, model provider (OpenAI, Anthropic, etc.), and runtime parameters like temperature and max tokens.

skill_t

Stores the "Expertise" of an agent in Markdown format. Skills are hierarchical and versioned.

tool_t & tool_param_t

The "Hands" of the agent. Defines executable functions, including REST endpoints, MCP server calls, or WASM scripts.

agent_skill_t & skill_tool_t

Maps agents to skills and skills to tools, implementing the Progressive Disclosure pattern where agents only see the tools required for their current skill context.

3. Hindsight Memory System

A biomimetic memory architecture that transitions from flat logs to structured "atoms of thought."

agent_memory_bank_t

Profiles for memory banks, defining the "Personality and Disposition" (e.g., skepticism, empathy) of the memory layer.

agent_memory_unit_t

The individual "Atoms" of memory. Each unit contains content and a vector embedding (384-dim) for semantic retrieval.

agent_memory_entity_t & agent_memory_link_t

A Knowledge Graph layer that resolves entities and causal/semantic relationships between memory units.

4. Session Management

agent_session_history_t

The "Source of Truth" for active conversations, linking specific sessions to their respective Hindsight memory banks.

DDL Specification

-- Workflow Definitions: Stores the Agentic Workflow JSON
CREATE TABLE wf_definition_t (
    host_id             UUID NOT NULL,
    wf_def_id           UUID NOT NULL,
    namespace           VARCHAR(126) NOT NULL,
    name                VARCHAR(126) NOT NULL,
    version             VARCHAR(20) NOT NULL,
    definition          TEXT NOT NULL, -- The Agentic Workflow DSL in YAML
    aggregate_version    BIGINT DEFAULT 1 NOT NULL,
    active              BOOLEAN DEFAULT TRUE,
    update_ts           TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP,
    update_user         VARCHAR(126) DEFAULT SESSION_USER,
    PRIMARY KEY(host_id, wf_def_id),
    UNIQUE(host_id, namespace, name, version)
);

CREATE TABLE worklist_t (
  host_id              UUID NOT NULL,
  assignee_id          VARCHAR(126) NOT NULL,
  category_id          VARCHAR(126) DEFAULT '(all)' NOT NULL,
  status_code          VARCHAR(10) DEFAULT 'Active' NOT NULL,
  app_id               VARCHAR(512) DEFAULT 'global' NOT NULL,
  aggregate_version    BIGINT DEFAULT 1 NOT NULL,
  active               BOOLEAN NOT NULL DEFAULT TRUE,
  update_user          VARCHAR (255) DEFAULT SESSION_USER NOT NULL,
  update_ts            TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP NOT NULL,
  PRIMARY KEY(host_id, assignee_id, category_id)
);

CREATE TABLE worklist_column_t (
  host_id               UUID NOT NULL,
  assignee_id           VARCHAR(126) NOT NULL,
  category_id           VARCHAR(126) DEFAULT '(all)' NOT NULL,
  sequence_id           INTEGER NOT NULL,
  column_id             VARCHAR(126) NOT NULL,
  aggregate_version     BIGINT DEFAULT 1 NOT NULL,
  active                BOOLEAN DEFAULT TRUE,
  update_ts             TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP,
  update_user           VARCHAR(126) DEFAULT SESSION_USER,
  PRIMARY KEY(host_id, assignee_id, category_id, sequence_id),
  FOREIGN KEY(host_id, assignee_id, category_id) REFERENCES worklist_t(host_id, assignee_id, category_id) ON DELETE CASCADE
);

CREATE TABLE process_info_t (
  host_id                    UUID NOT NULL,
  process_id                 UUID NOT NULL, -- generated uuid
  wf_def_id                  UUID NOT NULL, -- workflow definition id
  wf_instance_id             VARCHAR(126)       NOT NULL, -- workflow intance id
  app_id                     VARCHAR(512)       NOT NULL, -- application id
  process_type               VARCHAR(126)      NOT NULL,
  status_code                CHAR(1)            NOT NULL, -- process status code 'A', 'C'
  started_ts                 TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP NOT NULL,
  ex_trigger_ts              TIMESTAMP WITH TIME ZONE          NOT NULL,
  custom_status_code         VARCHAR(126),
  completed_ts               TIMESTAMP WITH TIME ZONE,
  result_code                VARCHAR(126),
  source_id                  VARCHAR(126),
  branch_code                VARCHAR(126),
  rr_code                    VARCHAR(126),
  party_id                   VARCHAR(126),
  party_name                 VARCHAR(126),
  counter_party_id           VARCHAR(126),
  counter_party_name         VARCHAR(126),
  txn_id                     VARCHAR(126),
  txn_name                   VARCHAR(126),
  product_id                 VARCHAR(126),
  product_name               VARCHAR(126),
  product_type               VARCHAR(126),
  group_name                 VARCHAR(126),
  subgroup_name              VARCHAR(126),
  event_start_ts             TIMESTAMP WITH TIME ZONE,
  event_end_ts               TIMESTAMP WITH TIME ZONE,
  event_other_ts             TIMESTAMP WITH TIME ZONE,
  event_other                VARCHAR(126),
  risk                       NUMERIC,
  risk_scale                 INTEGER,
  price                      NUMERIC,
  price_scale                INTEGER, -- Scale (number of digits to the right of the decimal) of the risk column. NULL implies zero
  product_qy                 NUMERIC,
  currency_code              CHAR(3),
  ex_ref_id                  VARCHAR(126),
  ex_ref_code                VARCHAR(126),
  product_qy_scale           INTEGER,
  parent_process_id          VARCHAR(22),
  deadline_ts                TIMESTAMP WITH TIME ZONE,
  parent_group_id            NUMERIC,
  process_subtype_code       VARCHAR(126),
  owning_group_name          VARCHAR(126), -- Name of the group that owns the process
  input_data                 JSONB,        -- The initial data that triggered the workflow
  context_data               JSONB,        -- The runtime "scratchpad" for intermediate variables
  error_info                 TEXT,         -- Detailed error or stack trace if the process fails
  aggregate_version   BIGINT DEFAULT 1 NOT NULL,
  active              BOOLEAN DEFAULT TRUE,
  update_ts           TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP,
  update_user         VARCHAR(126) DEFAULT SESSION_USER,
  PRIMARY KEY(host_id, process_id),
  FOREIGN KEY(host_id, wf_def_id) REFERENCES wf_definition_t(host_id, wf_def_id) ON DELETE CASCADE
);

CREATE TABLE task_info_t
(
    host_id             UUID NOT NULL,
    task_id             UUID NOT NULL,
    task_type           VARCHAR(126) NOT NULL,
    process_id          UUID NOT NULL,
    wf_instance_id      VARCHAR(126) NOT NULL,
    wf_task_id          VARCHAR(126) NOT NULL,
    status_code         CHAR(1)       NOT NULL, -- U, A, C
    started_ts          TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP NOT NULL,
    locked              CHAR(1)       NOT NULL,
    priority            INTEGER        NOT NULL,
    completed_ts        TIMESTAMP WITH TIME ZONE      NULL,
    completed_user      VARCHAR(126)     NULL,
    result_code         VARCHAR(126)     NULL,
    locking_user        VARCHAR(126)     NULL,
    locking_role        VARCHAR(126)     NULL,
    deadline_ts         TIMESTAMP WITH TIME ZONE      NULL,
    lock_group          VARCHAR(126)     NULL,
    task_input          JSONB,           -- Specific data passed to the task
    task_output         JSONB,           -- Result returned by the task action
    aggregate_version   BIGINT DEFAULT 1 NOT NULL,
    active              BOOLEAN DEFAULT TRUE,
    update_ts           TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP,
    update_user         VARCHAR(126) DEFAULT SESSION_USER,
    PRIMARY KEY(host_id, task_id),
    FOREIGN KEY (host_id, process_id) REFERENCES process_info_t(host_id, process_id) ON DELETE CASCADE
);

CREATE TABLE task_asst_t
(
    host_id             UUID NOT NULL,
    task_asst_id         UUID NOT NULL,
    task_id              UUID NOT NULL,
    assigned_ts          TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP NOT NULL,
    assignee_id          VARCHAR(126) NOT NULL,
    reason_code          VARCHAR(126) NOT NULL,
    unassigned_ts        TIMESTAMP WITH TIME ZONE      NULL,
    unassigned_reason    VARCHAR(126)     NULL,
    category_code        VARCHAR(126)     NULL,
    aggregate_version    BIGINT DEFAULT 1 NOT NULL,
    active               BOOLEAN DEFAULT TRUE,
    update_ts            TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP,
    update_user          VARCHAR(126) DEFAULT SESSION_USER,
    PRIMARY KEY(host_id, task_asst_id),
    FOREIGN KEY(host_id, task_id) REFERENCES task_info_t(host_id, task_id) ON DELETE CASCADE
);

CREATE TABLE audit_log_t
(
    host_id             UUID NOT NULL,
    audit_log_id        UUID NOT NULL,
    source_type_id      VARCHAR(126)      NULL,
    correlation_id      VARCHAR(126)      NULL,
    user_id             VARCHAR(126)     NULL,
    event_ts            TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP NOT NULL,
    success             CHAR(1)           NULL,
    message0            VARCHAR(126)     NULL,
    message1            VARCHAR(126)     NULL,
    message2            VARCHAR(126)     NULL,
    message3            VARCHAR(126)     NULL,
    message             VARCHAR(500)     NULL,
    user_comment        VARCHAR(500)     NULL,
    PRIMARY KEY(host_id, audit_log_id)
);

CREATE INDEX audit_log_idx1 ON audit_log_t (source_type_id, correlation_id, event_ts, user_id);

-- Agent Definitions: Stores the "Brain" configuration
CREATE TABLE agent_definition_t (
    host_id             UUID NOT NULL,
    agent_def_id        UUID NOT NULL,
    agent_name          VARCHAR(126) NOT NULL,
    model_provider      VARCHAR(64) NOT NULL,  -- 'openai', 'anthropic', etc.
    model_name          VARCHAR(126) NOT NULL, -- 'gpt-4o', 'claude-3-5-sonnet'
    api_key_ref         VARCHAR(126),          -- Reference to Secret Manager key
    temperature         NUMERIC(3,2) DEFAULT 0.7,
    max_tokens          INTEGER,               -- max number of tokens can be used
    aggregate_version    BIGINT DEFAULT 1 NOT NULL,
    active              BOOLEAN DEFAULT TRUE,
    update_ts           TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP,
    update_user         VARCHAR(126) DEFAULT SESSION_USER,
    PRIMARY KEY(host_id, agent_def_id),
    UNIQUE(host_id, agent_name)
);


-- Skills: Stores Instructions and Domain Knowledge (The "Expertise")
-- Note: Use entity_tag_t and entity_category_t with entity_type = 'skill' 
-- for flat tagging and hierarchical folder structure of skills.
CREATE TABLE skill_t (
    host_id             UUID NOT NULL,
    skill_id            UUID NOT NULL,
    parent_skill_id     UUID,                  -- Self-reference for Hierarchy
    name                VARCHAR(126) NOT NULL,
    description         VARCHAR(500),          -- High-level description for the initial LLM prompt
    content_markdown    TEXT NOT NULL,         -- The actual instructions/prompts

    description_embedding VECTOR(384),          -- For semantic lookup/discovery
    version             VARCHAR(20) DEFAULT '1.0.0',
    aggregate_version    BIGINT DEFAULT 1 NOT NULL,
    active              BOOLEAN DEFAULT true,
    update_ts           TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP,
    update_user         VARCHAR(126) DEFAULT SESSION_USER,
    PRIMARY KEY(host_id, skill_id),
    FOREIGN KEY(host_id, parent_skill_id) REFERENCES skill_t(host_id, skill_id)
);

CREATE INDEX idx_skill_active ON skill_t(active);
CREATE INDEX idx_skill_name ON skill_t(name);

-- Tools: Stores Executable Functions (The "Hands")
CREATE TABLE tool_t (
    host_id             UUID NOT NULL,
    tool_id             UUID NOT NULL,
    name                VARCHAR(126) NOT NULL,
    description         TEXT NOT NULL,         -- Instructions for LLM on when/how to use this tool

    -- Implementation specifics
    implementation_type VARCHAR(50),           -- 'java', 'mcp_server', 'rest', 'python', 'javascript'
    implementation_class VARCHAR(500),         -- FQCN if 'java'
    mcp_server_name      VARCHAR(126),         -- MCP server name if 'mcp_server'
    api_endpoint        VARCHAR(1024),         -- URL if 'rest'
    api_method          VARCHAR(10),           -- HTTP Method if 'rest'
    endpoint_id         UUID,                  -- Reference to fine-grained auth endpoint
    script_content      TEXT,                  -- Source code if 'python'/'javascript'
    response_schema     JSONB,                 -- Strict output schema for tool results

    description_embedding VECTOR(384),          -- For semantic lookup/discovery
    version             VARCHAR(20) DEFAULT '1.0.0',
    aggregate_version   BIGINT DEFAULT 1 NOT NULL,
    active              BOOLEAN DEFAULT true,
    update_ts           TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP,
    update_user         VARCHAR(126) DEFAULT SESSION_USER,
    PRIMARY KEY(host_id, tool_id),
    FOREIGN KEY(host_id, endpoint_id) REFERENCES api_endpoint_t(host_id, endpoint_id) ON DELETE CASCADE
);

CREATE INDEX idx_tool_host_endpoint ON tool_t(host_id, endpoint_id);
CREATE INDEX idx_tool_active ON tool_t(active);
CREATE INDEX idx_tool_name ON tool_t(name);

-- Tool Parameters: Defines the arguments for each tool
CREATE TABLE tool_param_t (
    host_id             UUID NOT NULL,
    param_id            UUID NOT NULL,
    tool_id             UUID NOT NULL,
    name                VARCHAR(255) NOT NULL,
    param_type          VARCHAR(50) NOT NULL,      -- 'string', 'number', 'boolean', 'object', 'array'
    required            BOOLEAN DEFAULT true,
    default_value       JSONB,
    description         TEXT,                      -- Helps LLM understand what value to extract
    validation_schema   JSONB,                     -- JSON Schema for complex validation
    order_index         INTEGER DEFAULT 0,
    aggregate_version   BIGINT DEFAULT 1 NOT NULL,
    active              BOOLEAN DEFAULT true,
    update_ts           TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP,
    update_user         VARCHAR(126) DEFAULT SESSION_USER,
    PRIMARY KEY(host_id, param_id),
    FOREIGN KEY(host_id, tool_id) REFERENCES tool_t(host_id, tool_id) ON DELETE CASCADE
);

-- Skill Dependencies: Manages hierarchies where one skill requires another
CREATE TABLE skill_dependency_t (
    host_id             UUID NOT NULL,
    skill_id            UUID NOT NULL,
    depends_on_skill_id UUID NOT NULL,
    required            BOOLEAN DEFAULT true,
    aggregate_version   BIGINT DEFAULT 1 NOT NULL,
    active              BOOLEAN DEFAULT true,
    update_ts           TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP,
    update_user         VARCHAR(126) DEFAULT SESSION_USER,
    PRIMARY KEY (host_id, skill_id, depends_on_skill_id),
    FOREIGN KEY(host_id, skill_id) REFERENCES skill_t(host_id, skill_id),
    FOREIGN KEY(host_id, depends_on_skill_id) REFERENCES skill_t(host_id, skill_id)
);

-- Agent-Skill Mapping: Links Agents to their Skills
CREATE TABLE agent_skill_t (
    host_id             UUID NOT NULL,
    agent_def_id        UUID NOT NULL,
    skill_id            UUID NOT NULL,

    config              JSONB DEFAULT '{}',
    priority            INTEGER DEFAULT 0,
    sequence_id         INTEGER DEFAULT 0,     -- Order in which skills are concatenated

    aggregate_version    BIGINT DEFAULT 1 NOT NULL,
    active              BOOLEAN DEFAULT true,
    update_ts           TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP,
    update_user         VARCHAR(126) DEFAULT SESSION_USER,
    PRIMARY KEY(host_id, agent_def_id, skill_id),
    FOREIGN KEY(host_id, agent_def_id) REFERENCES agent_definition_t(host_id, agent_def_id) ON DELETE CASCADE,
    FOREIGN KEY(host_id, skill_id) REFERENCES skill_t(host_id, skill_id) ON DELETE CASCADE
);
CREATE INDEX idx_agent_skill_agent ON agent_skill_t(agent_def_id);

-- Skill-Tool Mapping: Implements Progressive Disclosure
CREATE TABLE skill_tool_t (
    host_id             UUID NOT NULL,
    skill_id            UUID NOT NULL,
    tool_id             UUID NOT NULL,

    config              JSONB DEFAULT '{}',
    access_level        VARCHAR(20) DEFAULT 'read', -- e.g., 'read', 'write', 'execute'

    aggregate_version   BIGINT DEFAULT 1 NOT NULL,
    active              BOOLEAN DEFAULT true,
    update_ts           TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP,
    update_user         VARCHAR(126) DEFAULT SESSION_USER,
    PRIMARY KEY(host_id, skill_id, tool_id),
    FOREIGN KEY(host_id, skill_id) REFERENCES skill_t(host_id, skill_id) ON DELETE CASCADE,
    FOREIGN KEY(host_id, tool_id) REFERENCES tool_t(host_id, tool_id) ON DELETE CASCADE
);
CREATE INDEX idx_skill_tool_skill ON skill_tool_t(skill_id);

-- -- Hindsight Advanced Memory System
-- Transitioned from flat logs to biomimetic memory banks (World, Experiences, Mental Models)

-- Memory bank profiles (Personality & Disposition)
CREATE TABLE agent_memory_bank_t (
    host_id             UUID NOT NULL,
    bank_id             UUID NOT NULL,
    agent_def_id        UUID,                  -- NULL if bank is shared across agents
    user_id             UUID,                  -- NULL if bank is global for the host/agent
    bank_name           VARCHAR(126) NOT NULL,
    disposition         JSONB NOT NULL DEFAULT '{"skepticism": 3, "literalism": 3, "empathy": 3}'::jsonb,
    background          TEXT,
    aggregate_version   BIGINT DEFAULT 1 NOT NULL,
    active              BOOLEAN DEFAULT true,
    update_ts           TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP,
    update_user         VARCHAR(126) DEFAULT SESSION_USER,
    PRIMARY KEY(host_id, bank_id),
    FOREIGN KEY(host_id) REFERENCES host_t(host_id) ON DELETE CASCADE,
    FOREIGN KEY(host_id, agent_def_id) REFERENCES agent_definition_t(host_id, agent_def_id) ON DELETE CASCADE,
    FOREIGN KEY(user_id) REFERENCES user_t(user_id) ON DELETE CASCADE
);

-- Source documents for memory units
CREATE TABLE agent_memory_doc_t (
    host_id             UUID NOT NULL,
    doc_id              UUID NOT NULL,
    bank_id             UUID NOT NULL,
    original_text       TEXT,
    content_hash        TEXT,
    aggregate_version   BIGINT DEFAULT 1 NOT NULL,
    active              BOOLEAN DEFAULT true,
    update_ts           TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP,
    update_user         VARCHAR(126) DEFAULT SESSION_USER,
    PRIMARY KEY (host_id, bank_id, doc_id),
    FOREIGN KEY (host_id, bank_id) REFERENCES agent_memory_bank_t(host_id, bank_id) ON DELETE CASCADE
);

-- Individual sentence-level memories (The "Atoms" of thought)
CREATE TABLE agent_memory_unit_t (
    host_id             UUID NOT NULL,
    unit_id             UUID NOT NULL,
    bank_id             UUID NOT NULL,
    doc_id              UUID,
    content             TEXT NOT NULL,
    embedding           vector(384),
    context             TEXT,
    event_date          TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT now(),
    occurred_start      TIMESTAMP WITH TIME ZONE,
    occurred_end        TIMESTAMP WITH TIME ZONE,
    mentioned_at        TIMESTAMP WITH TIME ZONE,
    fact_type           VARCHAR(32) NOT NULL DEFAULT 'world' CHECK (fact_type IN ('world', 'experience', 'opinion', 'observation', 'mental_model')),
    metadata            JSONB DEFAULT '{}'::jsonb,
    proof_count         INT DEFAULT 1,
    source_memory_ids   UUID[] DEFAULT ARRAY[]::UUID[],
    aggregate_version   BIGINT DEFAULT 1 NOT NULL,
    active              BOOLEAN DEFAULT true,
    update_ts           TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP,
    update_user         VARCHAR(126) DEFAULT SESSION_USER,
    PRIMARY KEY(host_id, bank_id, unit_id),
    FOREIGN KEY(host_id, bank_id) REFERENCES agent_memory_bank_t(host_id, bank_id) ON DELETE CASCADE,
    FOREIGN KEY(host_id, bank_id, doc_id) REFERENCES agent_memory_doc_t(host_id, bank_id, doc_id) ON DELETE CASCADE
);

CREATE INDEX idx_mem_unit_bank ON agent_memory_unit_t(bank_id);
CREATE INDEX idx_mem_unit_embedding ON agent_memory_unit_t USING hnsw (embedding vector_cosine_ops);

-- Resolved entities (Knowledge Graph Nodes)
CREATE TABLE agent_memory_entity_t (
    host_id             UUID NOT NULL,
    entity_id           UUID NOT NULL,
    bank_id             UUID NOT NULL,
    user_id             UUID,                  -- Link to user_t if this entity is a platform user
    canonical_name      TEXT NOT NULL,
    mention_count       INT DEFAULT 1,
    metadata            JSONB DEFAULT '{}'::jsonb,
    aggregate_version   BIGINT DEFAULT 1 NOT NULL,
    active              BOOLEAN DEFAULT true,
    update_ts           TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP,
    update_user         VARCHAR(126) DEFAULT SESSION_USER,
    PRIMARY KEY (host_id, bank_id, entity_id),
    FOREIGN KEY (host_id, bank_id) REFERENCES agent_memory_bank_t(host_id, bank_id) ON DELETE CASCADE,
    FOREIGN KEY (user_id) REFERENCES user_t(user_id) ON DELETE CASCADE
);

-- Association between memory units and entities
CREATE TABLE agent_memory_unit_entity_t (
    host_id             UUID NOT NULL,
    bank_id             UUID NOT NULL,
    unit_id             UUID NOT NULL,
    entity_id           UUID NOT NULL,
    PRIMARY KEY (host_id, bank_id, unit_id, entity_id),
    FOREIGN KEY (host_id, bank_id, unit_id) REFERENCES agent_memory_unit_t(host_id, bank_id, unit_id) ON DELETE CASCADE,
    FOREIGN KEY (host_id, bank_id, entity_id) REFERENCES agent_memory_entity_t(host_id, bank_id, entity_id) ON DELETE CASCADE
);

-- Cache of entity co-occurrences (Concept Relationship Graph)
CREATE TABLE agent_memory_entity_cooccur_t (
    host_id             UUID NOT NULL,
    bank_id             UUID NOT NULL,
    entity_id_1         UUID NOT NULL,
    entity_id_2         UUID NOT NULL,
    cooccur_count       INT DEFAULT 1,
    last_cooccurred     TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP,
    aggregate_version   BIGINT DEFAULT 1 NOT NULL,
    active              BOOLEAN DEFAULT true,
    update_ts           TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP,
    update_user         VARCHAR(126) DEFAULT SESSION_USER,
    PRIMARY KEY (host_id, bank_id, entity_id_1, entity_id_2),
    CONSTRAINT entity_cooccur_order_check CHECK (entity_id_1 < entity_id_2),
    FOREIGN KEY (host_id, bank_id, entity_id_1) REFERENCES agent_memory_entity_t(host_id, bank_id, entity_id) ON DELETE CASCADE,
    FOREIGN KEY (host_id, bank_id, entity_id_2) REFERENCES agent_memory_entity_t(host_id, bank_id, entity_id) ON DELETE CASCADE
);

CREATE INDEX idx_mem_cooccur_e1 ON agent_memory_entity_cooccur_t(host_id, entity_id_1);
CREATE INDEX idx_mem_cooccur_e2 ON agent_memory_entity_cooccur_t(host_id, entity_id_2);

-- Links between memory units (Semantic & Causal relationships)
CREATE TABLE agent_memory_link_t (
    host_id             UUID NOT NULL,
    bank_id             UUID NOT NULL,
    from_unit_id        UUID NOT NULL,
    to_unit_id          UUID NOT NULL,
    link_type           VARCHAR(32) NOT NULL,
    weight              FLOAT NOT NULL DEFAULT 1.0,
    aggregate_version   BIGINT DEFAULT 1 NOT NULL,
    active              BOOLEAN DEFAULT true,
    update_ts           TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP,
    update_user         VARCHAR(126) DEFAULT SESSION_USER,
    PRIMARY KEY (host_id, bank_id, from_unit_id, to_unit_id, link_type),
    CONSTRAINT memory_links_type_check CHECK (link_type IN ('temporal', 'semantic', 'entity', 'causes', 'caused_by', 'enables', 'prevents')),
    FOREIGN KEY (host_id, bank_id, from_unit_id) REFERENCES agent_memory_unit_t(host_id, bank_id, unit_id) ON DELETE CASCADE,
    FOREIGN KEY (host_id, bank_id, to_unit_id) REFERENCES agent_memory_unit_t(host_id, bank_id, unit_id) ON DELETE CASCADE
);

-- Directives (Hard rules that override probabilistic learning)
CREATE TABLE agent_memory_directive_t (
    host_id             UUID NOT NULL,
    directive_id        UUID NOT NULL,
    bank_id             UUID NOT NULL,
    name                VARCHAR(256) NOT NULL,
    content             TEXT NOT NULL,
    priority            INT NOT NULL DEFAULT 0,
    aggregate_version   BIGINT DEFAULT 1 NOT NULL,
    active              BOOLEAN DEFAULT true,
    update_ts           TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP,
    update_user         VARCHAR(126) DEFAULT SESSION_USER,
    PRIMARY KEY(host_id, bank_id, directive_id),
    FOREIGN KEY(host_id, bank_id) REFERENCES agent_memory_bank_t(host_id, bank_id) ON DELETE CASCADE
);

-- Reflections (Synthesized knowledge and high-level observations)
CREATE TABLE agent_memory_reflection_t (
    host_id             UUID NOT NULL,
    reflection_id       UUID NOT NULL,
    bank_id             UUID NOT NULL,
    content             TEXT NOT NULL,
    embedding           vector(384),
    aggregate_version   BIGINT DEFAULT 1 NOT NULL,
    active              BOOLEAN DEFAULT true,
    update_ts           TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP,
    update_user         VARCHAR(126) DEFAULT SESSION_USER,
    PRIMARY KEY(host_id, bank_id, reflection_id),
    FOREIGN KEY(host_id, bank_id) REFERENCES agent_memory_bank_t(host_id, bank_id) ON DELETE CASCADE
);

CREATE INDEX idx_mem_reflection_embedding ON agent_memory_reflection_t USING hnsw (embedding vector_cosine_ops);

-- Raw Session History (The source of Truth for active conversations)
CREATE TABLE agent_session_history_t (
    host_id             UUID NOT NULL,
    session_id          UUID NOT NULL,
    bank_id             UUID NOT NULL,         -- Links the session to a Hindsight bank
    messages            JSONB NOT NULL DEFAULT '[]'::jsonb,
    metadata            JSONB DEFAULT '{}'::jsonb,
    aggregate_version   BIGINT DEFAULT 1 NOT NULL,
    active              BOOLEAN DEFAULT true,
    update_ts           TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP,
    update_user         VARCHAR(126) DEFAULT SESSION_USER,
    PRIMARY KEY(host_id, bank_id, session_id),
    FOREIGN KEY(host_id, bank_id) REFERENCES agent_memory_bank_t(host_id, bank_id) ON DELETE CASCADE
);

CREATE INDEX idx_session_bank ON agent_session_history_t(host_id, bank_id);

Light-Deployer Design

light-deployer is the cluster-local Kubernetes deployment executor in Light Fabric.

This document focuses only on the deployer service that lives in apps/light-deployer. The broader Light Portal deployment workflow, approval flow, deployment history model, controller routing, and portal UI are covered outside this repository.

Purpose

light-deployer receives a deployment command, fetches Kubernetes templates, renders them with deployment values, validates the resulting resources, applies or deletes resources in the target Kubernetes cluster, and returns safe status details.

It is intentionally narrow. It does not decide whether a user is allowed to deploy an instance, does not own portal deployment history, and does not create tenant business workflows. Those decisions belong to Light Portal, Light Controller, and the workflow engine.

Service Boundary

light-deployer owns:

• local deployment policy enforcement
• template repository fetch
• YAML template rendering
• manifest parsing and resource summary generation
• Kubernetes dry-run, apply, delete, status, and pruning
• safe event and error reporting
• direct local/MicroK8s deployment endpoints

light-deployer does not own:

• tenant authorization
• instance metadata
• deployment approval
• deployment history persistence
• config snapshot creation
• long-running human workflow decisions

The deployer should reject commands outside its local policy even if an upstream service sends them.

Runtime Model

The service follows the same runtime pattern as light-agent.

main.rs builds the domain service and starts it through:

#![allow(unused)]
fn main() {
LightRuntimeBuilder::new(AxumTransport::new(app))
}

The HTTP listener is owned by light-runtime and light-axum, not by service-specific socket code. Bind address, HTTP/HTTPS ports, service identity, and registry settings live in runtime config files.

Default config files:

• config/server.yml
• config/deployer.yml
• config/portal-registry.yml

Local cargo run resolves config from apps/light-deployer/config when run from the workspace root. The container image runs from /app and uses /app/config.

Public Endpoints

Phase 1 exposes a direct HTTP surface for local and MicroK8s testing:

GET  /health
GET  /ready
POST /mcp
GET  /mcp/tools
GET  /mcp/tools/list
GET  /mcp/tools/{tool}
POST /deployments
POST /mcp/tools/{tool}
GET  /events?request_id=...

POST /mcp is the MCP JSON-RPC 2.0 endpoint. It supports tools/list, tools/call, and a minimal initialize response. This is the endpoint that MCP clients, Light Portal, and AI agents should use.

/deployments accepts the canonical deployment request directly. /mcp/tools/{tool} maps tool names onto the same internal service functions as a REST-style local debugging convenience. The convenience tool-list endpoints return metadata with name, description, inputSchema, endpoint, and method, but they are not the MCP protocol endpoint.

Supported tool names:

• deployment.render
• deployment.dryRun
• deployment.diff
• deployment.apply
• deployment.delete
• deployment.status
• deployment.rollback

The direct HTTP mode is useful for development and managed environments. The same internal command handling should later be reused by controller-mediated WebSocket/MCP routing.

Request Model

A deployment request is explicit and auditable.

{
  "requestId": "01964b05-0000-7000-8000-000000000001",
  "hostId": "01964b05-552a-7c4b-9184-6857e7f3dc5f",
  "instanceId": "petstore-dev",
  "environment": "dev",
  "clusterId": "microk8s-local",
  "namespace": "petstore-dev",
  "action": "deploy",
  "values": {
    "name": "petstore",
    "image": {
      "repository": "networknt/openapi-petstore",
      "tag": "latest"
    }
  },
  "template": {
    "repoUrl": "https://github.com/networknt/openapi-petstore.git",
    "ref": "master",
    "path": "k8s"
  },
  "options": {
    "dryRun": false,
    "waitForRollout": true,
    "timeoutSeconds": 300,
    "pruneOverride": false
  }
}

The current implementation supports inline values. The request model also contains fields for future values references and immutable snapshot metadata so it can align with the full portal deployment workflow.

When invoking a specific /mcp/tools/{tool} endpoint, callers do not need to send action. The deployer derives the action from the tool name. The generic /deployments endpoint still expects an explicit action in the request body.

For the MCP endpoint, callers use JSON-RPC:

{
  "jsonrpc": "2.0",
  "id": "tools-list-1",
  "method": "tools/list",
  "params": {}
}

Tool invocation uses tools/call:

{
  "jsonrpc": "2.0",
  "id": "render-1",
  "method": "tools/call",
  "params": {
    "name": "deployment.render",
    "arguments": {
      "hostId": "local-host",
      "instanceId": "petstore-dev",
      "environment": "dev",
      "clusterId": "local",
      "namespace": "light-deployer",
      "values": {},
      "template": {
        "repoUrl": "local",
        "ref": "main",
        "path": "k8s"
      }
    }
  }
}

tools/call derives the deployment action from params.name; callers should not provide an action field in arguments.

Actions

render : Fetch templates, render manifests, add namespaces and management labels, and return resource summaries plus a manifest hash.

dryRun : Render manifests and validate them against Kubernetes using server-side dry-run.

diff : Render manifests, fetch current managed resources, calculate additions, modifications, and pruned resources, and return a redacted diff summary.

deploy : Accept the request, run the deployment in the background, apply manifests, prune removed managed resources, and stream events.

undeploy : Delete resources associated with the deployment.

status : Return current managed resource status.

rollback : Reserved for redeploying a previous immutable portal snapshot. Native Kubernetes rollout undo is not the target rollback model because it does not restore ConfigMaps, Secrets, or values snapshots.

Template Fetching

Templates are loaded through the TemplateSource trait.

The current source supports two modes:

• local template root through LIGHT_DEPLOYER_TEMPLATE_BASE_DIR
• remote HTTPS Git clone through gix

For remote repositories, the deployment request provides:

{
  "template": {
    "repoUrl": "https://github.com/networknt/openapi-petstore.git",
    "ref": "master",
    "path": "k8s"
  }
}

Private HTTPS Git access is controlled by environment variables:

• LIGHT_DEPLOYER_GIT_TOKEN: token or app password
• LIGHT_DEPLOYER_GIT_USERNAME: optional username override

Defaults:

• GitHub uses x-access-token
• Bitbucket Cloud uses x-token-auth

SSH authentication is intentionally deferred because it requires private key handling and strict known_hosts validation.

Template Format

The built-in renderer uses simple placeholders:

image: ${image.repository}:${image.tag:latest}

Supported behavior:

• nested paths such as image.repository
• default values after :
• render failure when a required value is missing
• placeholder replacement only inside YAML string scalar values

The renderer parses YAML into serde_yaml::Value, traverses the AST, replaces placeholders, and serializes or applies structured YAML values afterward. This avoids the most common raw string replacement bugs around quoting, indentation, certificates, and multi-line values.

Because placeholders currently produce strings, templates should avoid placeholders in numeric-only Kubernetes fields unless Kubernetes accepts a string value there. For example, containerPort should be fixed or rendered by a future typed placeholder extension.

Resource Metadata

After rendering, the deployer ensures every resource has the target namespace and adds management labels:

• app.kubernetes.io/managed-by=light-deployer
• lightapi.net/host-id
• lightapi.net/instance-id
• lightapi.net/request-id

These labels are used for status lookup and pruning.

Kubernetes Execution

Kubernetes execution is behind the KubeExecutor trait.

Current implementations:

• KubeRsExecutor: real Kubernetes API execution through kube-rs
• NoopKubeExecutor: local render/test mode

Execution mode:

• LIGHT_DEPLOYER_KUBE_MODE=real: force real Kubernetes mode
• LIGHT_DEPLOYER_KUBE_MODE=noop: force no-op mode
• default: real mode when KUBERNETES_SERVICE_HOST is present, otherwise no-op

The production path uses kube-rs, not kubectl.

Kubernetes operations should use:

• in-cluster ServiceAccount auth when running as a pod
• server-side dry-run for validation
• server-side apply with field manager light-deployer
• structured status and error handling

Pruning

The deployer is declarative. If a previously managed resource is no longer rendered from the template, it should be considered for pruning.

Pruning is calculated by comparing:

• current resources in the namespace with lightapi.net/instance-id
• resources rendered from the new template

The policy layer enforces blast-radius protection:

• maximum delete percentage
• sensitive kinds requiring override
• explicit pruneOverride in deployment options

This prevents stale resources while still protecting against accidental large-scale deletion.

Policy

The local deployer.yml policy constrains what a deployer is allowed to do.

Policy dimensions:

• allowed namespaces
• allowed repository hosts
• allowed repository URL prefixes
• allowed image registries
• allowed actions
• allowed Kubernetes kinds
• blocked Kubernetes kinds
• prune settings
• development insecure mode

Version 1 allows application-level resource kinds by default:

• Deployment
• Service
• Ingress
• ConfigMap
• Secret

Cluster-scoped and control-plane resources are blocked by default:

• Namespace
• ClusterRole
• ClusterRoleBinding
• CustomResourceDefinition
• admission webhooks

Security

The deployer can mutate a Kubernetes cluster, so its default posture must be conservative.

Required practices:

• run in Kubernetes with a dedicated ServiceAccount
• prefer namespace-scoped Role and RoleBinding
• restrict allowed namespaces and resource kinds
• restrict template repository hosts or prefixes in production
• restrict image registries in production
• never log raw rendered Secret manifests
• never log raw Kubernetes patch/apply payloads containing Secret data
• return redacted summaries and diffs

Secret values in rendered manifests are redacted before being included in responses or diffs. Kubernetes Secret values are base64 encoded, not encrypted, so they must be treated as plaintext for logging purposes.

Response Model

Responses include enough detail for callers to understand what happened without exposing secrets.

Important fields:

• requestId
• action
• status
• deployerId
• clusterId
• namespace
• manifestHash
• templateCommitSha
• resources
• diff
• events
• error

Resource summaries contain kind, namespace, name, apiVersion, and action. Full rendered manifests should not be returned or persisted by default.

Event Model

Long-running operations return quickly and continue in the background.

Clients can subscribe to:

GET /events?request_id=...

Events contain:

• request ID
• timestamp
• status
• message
• optional resource identity

The event stream is currently direct SSE. Controller-mediated mode can forward the same event shape later.

Installation

The app includes Kubernetes install manifests under apps/light-deployer/k8s:

• namespace
• RBAC
• deployment
• service

The deployment runs the container with LIGHT_DEPLOYER_KUBE_MODE=real. The image contains /app/config, and server.yml defaults the HTTP port to 7088.

For MicroK8s testing:

./apps/light-deployer/build.sh latest
docker save networknt/light-deployer:latest | microk8s ctr image import -
microk8s kubectl apply -f apps/light-deployer/k8s/namespace.yaml
microk8s kubectl apply -f apps/light-deployer/k8s/rbac.yaml
microk8s kubectl apply -f apps/light-deployer/k8s/deployment.yaml
microk8s kubectl apply -f apps/light-deployer/k8s/service.yaml

Current Limitations

• Direct HTTP/MCP-style mode is implemented first; controller-mediated WebSocket routing is a later integration step.
• Inline values are implemented; config-server valuesRef fetching is still a future integration point.
• Rollback is represented in the model but needs portal snapshot integration.
• Helm and Kustomize are not implemented yet.
• Typed placeholders are not implemented yet.
• Rollout watch depth is intentionally basic in the first phase.

Design Direction

Keep light-deployer small and cluster-local.

The deployer should execute precise deployment commands, enforce local safety policy, and report structured results. It should not grow into a portal, workflow engine, or deployment database. That separation keeps the service easy to install inside customer clusters and reduces the security blast radius.

Module Registry

Status: Phase 4 implemented for light-gateway/gateway; additional module reloaders remain planned.

Purpose

Light Fabric needs a runtime module registry equivalent to the ModuleRegistry feature in light-4j.

In light-4j, each active component registers its runtime configuration when the component loads. Older integrations exposed this through the /adm/server/info REST endpoint, but the current control-plane path uses MCP tools through portal-registry. The same registry is also used by the config-reload operation to decide which modules can reload configuration from the config server.

Light Fabric already has structured config files and a shared runtime startup flow, but it does not yet have a central registry that answers these operational questions:

• which modules are active in this running instance
• which config file each module loaded
• what masked runtime config is currently active
• which modules can be reloaded without restarting the process
• what happened during the last reload attempt

This document proposes a registry in light-runtime so every Light Fabric application can expose the same control-plane behavior.

Goals

• Register built-in runtime configs such as startup, server, client, and portal-registry.
• Register application configs such as gateway, deployer, ollama, and mcp-client.
• Store only masked config snapshots in the registry.
• Expose a Java-compatible server-info payload through the get_service_info MCP tool.
• Expose a module list through the get_modules MCP tool for config reload selection.
• Support control-plane reload requests for one module, several modules, or all modules through the reload_modules MCP tool. Phase 3 reports non-reloadable modules as skipped. Phase 4 adds real hot reload for light-gateway/gateway.
• Keep the feature transport-neutral by routing management requests through portal-registry, not through framework-specific REST routes.

Non-Goals

• Do not make every config hot-reloadable in the first phase.
• Do not rebind server ports or TLS listeners unless a transport explicitly supports it.
• Do not expose decrypted secrets through diagnostics.
• Do not make Rust type names part of the public control-plane contract.
• Do not add /adm/... REST endpoints for Light Fabric.

Current Light Fabric Runtime Shape

The natural home for this feature is crates/light-runtime.

LightRuntimeBuilder already owns the startup sequence:

1. load local bootstrap config
2. optionally fetch remote config from config server
3. build RuntimeConfig
4. call registered runtime modules
5. bind the transport
6. register the running instance with the controller
7. mark the runtime ready

RuntimeConfig already carries the merged resolved_values, config_dir, and external_config_dir. Application code can use those fields to load resolved application config without reparsing values.yml.

The config registry should build on that runtime boundary instead of creating a separate app-local registry per product.

Registry Model

Add a shared registry type in light-runtime.

#![allow(unused)]
fn main() {
pub struct ModuleRegistry {
    entries: RwLock<BTreeMap<String, ModuleEntry>>,
    reloaders: RwLock<BTreeMap<String, Arc<dyn ReloadableModule>>>,
}

pub struct ModuleEntry {
    pub module_id: String,
    pub config_name: String,
    pub kind: ModuleKind,
    pub active: bool,
    pub enabled: Option<bool>,
    pub reloadable: bool,
    pub config: serde_json::Value,
    pub masks: Vec<MaskSpec>,
    pub loaded_at: DateTime<Utc>,
    pub last_reload: Option<ReloadStatus>,
}

pub enum ModuleKind {
    Core,
    Framework,
    Application,
    Plugin,
}
}

Use stable module IDs instead of Rust type names. Java uses class names because they are stable operational identifiers in the JVM. Rust type names are not a good public API and can change during refactoring.

Example module IDs:

• light-runtime/startup
• light-runtime/server
• light-client/client
• light-runtime/portal-registry
• light-gateway/gateway
• light-deployer/deployer
• light-agent/ollama
• light-agent/mcp-client

The registry key should be module_id. Each entry also carries config_name so the server-info response can preserve the Java-style component map keyed by config name.

Registered Config Loading

Add a small registered-loader API around the existing ConfigLoader behavior.

#![allow(unused)]
fn main() {
let gateway_config: GatewayConfig = context
    .config()
    .load_registered(
        "gateway",
        "light-gateway/gateway",
        [MaskSpec::key("password")],
    )?;
}

The helper should:

1. merge the base file from config_dir
2. overlay the external file from external_config_dir
3. resolve variables from RuntimeConfig.resolved_values
4. deserialize the typed config
5. serialize the resolved config to serde_json::Value
6. apply masks to the serialized copy
7. store only the masked copy in ModuleRegistry
8. return the typed config to the caller

This keeps the app code simple and prevents accidental registry entries that contain raw secrets.

Phase 2 added this shared registered-loader path in ModuleRegistry and attached the registry to RuntimeConfig so apps that load after runtime bootstrap can register resolved config through the same runtime-owned registry. Apps that load before runtime startup can create the registry first, register their application configs, and pass that registry into LightRuntimeBuilder. For modules that must validate typed config before changing the registry snapshot, the same loader is also available as load_config(...) followed by register_loaded_config(...) after validation succeeds.

Masking

Masking must happen at registration time. The registry should not store raw config and then mask it later.

Support two mask forms:

#![allow(unused)]
fn main() {
pub enum MaskSpec {
    Key(String),
    Path(String),
}
}

MaskSpec::Key("password") masks every matching key recursively, matching the current light-4j behavior.

MaskSpec::Path("oauth.clientSecret") masks a precise path for configs where a generic key would be too broad.

Suggested default masks:

• authorization
• password
• secret
• clientSecret
• apiKey
• token
• portalToken
• controllerDiscoveryToken
• privateKey
• tlsKeyPath
• bootstrapKeyPath

Add a runtime flag such as server.maskConfigProperties or admin.maskConfigProperties, defaulting to true, for parity with the Java server.maskConfigProperties behavior. Even if this flag is disabled, the control-plane documentation should treat unmasked output as a local debugging mode only.

Server Info MCP Response

The get_service_info MCP tool response should preserve the same logical shape that portal-view already understands from Java instances.

{
  "deployment": {
    "apiVersion": "0.1.0",
    "frameworkVersion": "0.1.0"
  },
  "environment": {
    "host": {
      "ip": "127.0.0.1",
      "hostname": "light-gateway-0"
    },
    "runtime": {},
    "system": {}
  },
  "security": {},
  "component": {
    "server": {},
    "gateway": {}
  },
  "plugin": {},
  "plugins": [],
  "modules": []
}

component should remain keyed by config_name for compatibility.

modules should provide richer Rust metadata:

[
  {
    "moduleId": "light-gateway/gateway",
    "configName": "gateway",
    "kind": "application",
    "active": true,
    "enabled": true,
    "reloadable": true,
    "loadedAt": "2026-05-07T14:30:00Z",
    "lastReload": {
      "status": "success",
      "message": "reloaded from config server",
      "completedAt": "2026-05-07T14:45:00Z"
    }
  }
]

MCP Access

Expose the registry only through MCP tools served by the runtime's portal-registry connection.

MCP tools:

get_service_info
get_modules
reload_modules

These are invoked through standard MCP JSON-RPC calls:

{
  "jsonrpc": "2.0",
  "id": "info-1",
  "method": "tools/call",
  "params": {
    "name": "get_service_info",
    "arguments": {}
  }
}

The controller remains the management channel. portal-registry receives the MCP request from the controller, dispatches it to the local runtime registry, and returns the result through the same websocket session. Light Fabric should not expose a parallel REST admin surface for this feature.

For compatibility with the existing Java and portal-view workflow, get_modules returns a string list of module IDs:

{
  "modules": [
    "light-runtime/server",
    "light-gateway/gateway"
  ]
}

The richer module metadata remains available in the modules field of get_service_info.

Reload Request

The reload_modules tool should accept omitted arguments, ALL, or explicit module IDs.

{
  "modules": [
    "light-gateway/gateway",
    "light-runtime/portal-registry"
  ]
}

An omitted modules value, an empty array, or ["ALL"] targets all registered modules. Registered modules without concrete reload implementations are reported as skipped instead of being marked as reloaded.

The response should be explicit about what happened:

{
  "modules": ["light-gateway/gateway"],
  "reloaded": ["light-gateway/gateway"],
  "skipped": [
    {
      "moduleId": "light-runtime/server",
      "reason": "requiresRestart"
    }
  ],
  "failed": [
    {
      "moduleId": "light-agent/ollama",
      "message": "missing ollama.yml"
    }
  ]
}

modules is a Java-compatible alias for the successfully reloaded module IDs and is the field portal-view reads today. reloaded, skipped, and failed carry the more explicit Rust result details.

Reload Implementation

Phase 4 adds a reload trait for modules that can safely swap runtime config.

#![allow(unused)]
fn main() {
#[async_trait]
pub trait ReloadableModule: Send + Sync {
    async fn reload(&self, ctx: ReloadContext) -> Result<ReloadOutcome, RuntimeError>;
}
}

ReloadContext includes:

• a refreshed RuntimeConfig
• updated resolved_values
• the existing config_dir
• the existing external_config_dir
• the shared ModuleRegistry

Reload flow:

1. Re-fetch values.yml, certs, and files from the config server into external_config_dir.
2. Rebuild the merged resolved_values.
3. Resolve requested module IDs.
4. For each reloadable module, call its reload implementation.
5. Each module validates the new typed config before swapping it into live state.
6. Update the registry entry and last_reload status.
7. Return a detailed reload result.

Use ConfigManager<T> or another ArcSwap-backed holder for modules that need hot reload. This avoids locking the request path while still allowing atomic config replacement.

Phase 4 implements this with ConfigManager<T> in light-runtime. It stores an Arc<T> behind a short-lived RwLock, so request handlers clone the current config quickly and reloaders replace the entire typed config only after the new config has loaded and validated.

Reloadability Rules

Classify configs by reload safety.

Reloadable candidates:

• light-gateway/gateway
• light-deployer/deployer
• light-agent/ollama
• light-agent/mcp-client
• route, policy, provider, or rule configs that are already read through swappable state

Requires restart by default:

• bind IP
• HTTP/HTTPS port
• protocol enablement
• TLS certificate path used by the listener
• runtime config directory
• config-server bootstrap identity
• controller registration identity

Some server.yml fields can still be reloadable later, such as shutdownGracefulPeriod, but listener-affecting fields should stay requiresRestart until each transport supports safe rebinding.

Framework Integration

The registry should not require each framework to expose admin routes.

light-runtime should attach an MCP-capable RegistryHandler to the portal-registry client. When the controller invokes tools/list or tools/call, the handler can advertise and execute the local management tools without involving light-axum or light-pingora request routing.

This keeps light-axum and light-pingora focused on application traffic. It also avoids adding service ports, Kubernetes routes, or Pingora request filters only for control-plane operations.

Application Integration

light-gateway is integrated first because it already loads gateway.yml from RuntimeConfig.resolved_values, config_dir, and external_config_dir. It loads the resolved typed config, validates upstreams, and then stores the masked registry snapshot. In Phase 4, light-gateway/gateway also registers a ReloadableModule that reloads and validates gateway.yml, updates the masked registry snapshot, and swaps the live GatewayConfig through ConfigManager.

light-deployer loads deployer.yml before the runtime is started, so it creates a ModuleRegistry before loading its config, registers the final env-overridden deployer config, and passes the same registry to LightRuntimeBuilder.

light-agent also loads application configs before runtime startup. It now registers ollama.yml and mcp-client.yml in the pre-runtime registry and passes that registry into LightRuntimeBuilder. The existing manual PortalRegistryClient setup is unchanged so the registry feature does not reintroduce duplicate controller registration.

Current Registered Modules

Phase 4 registers these modules:

The application modules are visible in get_service_info once their owning application loads them. get_modules returns the corresponding module ID strings for portal-view selection. light-gateway/gateway can reload without a restart. Other application modules keep reloadable=false until their runtime state is moved behind swappable holders.

Rollout Plan

Phase 1: Registry and Masked Info

• Implemented: ModuleRegistry, ModuleEntry, and mask utilities in light-runtime.
• Implemented: built-in runtime config registration.
• Implemented: tests proving raw secrets are not stored in registry entries.
• Implemented: Java-compatible server-info response assembly.
• Implemented: module-list response.
• Implemented: a portal-registry MCP handler that exposes get_service_info and get_modules.

Phase 2: Application Registration

• Implemented: convert light-gateway/gateway to registered config loading.
• Implemented: convert light-deployer/deployer.
• Implemented: convert light-agent/ollama and light-agent/mcp-client.
• Implemented: add docs showing module IDs and reloadability.

Phase 3: Controller Operations

• Implemented: add MCP tools/list and tools/call support for reload_modules.
• Implemented: align portal-view calls so Java and Rust instances can be managed with the same control-plane workflow.
• Implemented: return Java-compatible modules string lists while preserving detailed reloaded, skipped, and failed reload result fields.

Phase 4: Hot Reload

• Implemented: add ReloadableModule, ReloadContext, and ReloadOutcome.
• Implemented: add ConfigManager<T> for swappable typed configs.
• Implemented: implement reload for light-gateway/gateway.
• Implemented: add reload result tracking in the registry.
• Implemented: add tests for registry reload results, gateway live config swapping, and config-server-backed reload context refresh.

Open Questions

• Should module IDs be centrally reserved in light-runtime, or should each application own its ID namespace?
• Should the Java-compatible component map include only active modules, while modules includes inactive-but-known modules?
• Should MCP tool execution be enabled whenever portal-registry is enabled, or guarded by a separate admin-tools flag?
• Should server.maskConfigProperties=false be allowed in production builds, or should Rust always mask known dangerous keys?

Implementation Sequence

Phase 1 implemented registry and masked server info first, without hot reload.

Phase 2 added application registration, so portal-view can display Rust application modules next to Java modules once it calls the MCP tools through portal-registry.

Phase 3 added the controller-facing reload_modules tool and Java-compatible module ID lists.

Phase 4 added the first real hot reload implementation for light-gateway/gateway. The next implementation step is to move additional application configs, such as light-deployer/deployer, light-agent/ollama, and light-agent/mcp-client, behind swappable runtime state before marking them reloadable.

Cache Control Plane

Status: Proposed

Purpose

Light Fabric should expose the same cache operations through the portal control plane that Java services expose through light-4j and portal-registry.

Today, portal-view can list caches and inspect cache entries for a running service instance. The next required operation is clearing a cache so cached data can be reloaded from its source of truth after operational data changes. A common case is clearing the reference-data cache in portal-service after reference tables are changed from light-portal.

The feature should be generic. It should not be a portal-service only endpoint. Any Java or Rust service that registers with the controller and has named local caches should be manageable through the same MCP tool contract.

Current Shape

The Java implementation already has most of the control-plane pieces:

• light-4j/cache-manager defines the generic CacheManager API.
• light-4j/caffeine-cache provides the Caffeine-backed implementation.
• light-4j/portal-registry exposes MCP tools such as list_caches and get_cache_entries.
• controller-rs and the Java controller forward instance-specific MCP tool calls by runtimeInstanceId.
• portal-view calls the controller MCP websocket and passes runtimeInstanceId for cache exploration.

The main semantic gap is that CacheManager.removeCache(name) removes the cache from the manager in the Caffeine implementation. For a control-plane clear operation, the desired behavior is different: invalidate all entries while keeping the configured cache alive so the next application read repopulates it.

Goals

• Add a generic whole-cache clear operation.
• Keep the control-plane contract compatible between Java services and Light Fabric services.
• Expose cache operations through portal-registry and controller MCP routing, not through service-specific REST endpoints.
• Let portal-view clear a selected cache from the existing Cache Explorer page.
• Use the same feature for portal-service reference data caching.
• Preserve existing cache inspection behavior.

Non-Goals

• Do not remove or unregister a configured cache when clearing entries.
• Do not require every service to use the same cache backend.
• Do not expose raw secrets or unsafe object internals through cache inspection.
• Do not build event-driven cross-service cache invalidation in the first phase.
• Do not confuse runtime data caches with the config-cache directory used for remote configuration files.

MCP Tool Contract

Add a new generic tool:

{
  "name": "clear_cache",
  "description": "Clear all entries from a named cache on a live runtime instance.",
  "inputSchema": {
    "type": "object",
    "required": ["runtimeInstanceId", "name"],
    "properties": {
      "runtimeInstanceId": { "type": "string", "format": "uuid" },
      "name": { "type": "string" }
    }
  }
}

The controller accepts runtimeInstanceId, removes it from the forwarded arguments, and sends this to the target runtime:

{
  "name": "clear_cache",
  "arguments": {
    "name": "reference-data"
  }
}

Recommended success response:

{
  "supported": true,
  "status": "success",
  "name": "reference-data",
  "beforeSize": 42,
  "afterSize": 0
}

Recommended unsupported response:

{
  "supported": false,
  "status": "unsupported",
  "name": "reference-data",
  "message": "Cache support is not available on this service."
}

Key-level invalidation can be added later as a separate invalidate_cache_entry tool with { "name": "...", "key": "..." }. Whole-cache clear should be implemented first because it solves the reference data reload case without introducing cache-key UX and serialization questions.

Java Compatibility Work

In light-4j, add an explicit clear operation to the generic cache API:

void clear(String cacheName);

The Caffeine implementation should call cache.invalidateAll() and keep the cache in the manager. It may call cache.cleanUp() before returning size data. removeCache(name) should keep its existing unregister/remove semantics.

portal-registry should advertise clear_cache in tools/list and handle it in tools/call by using CacheManager.getInstance(). The handler should return supported: false when cache classes or a cache manager are not available, matching the current list_caches and get_cache_entries behavior.

The controller catalogs need the same tool so portal-view can call it through the normal controller websocket:

• controller-rs tool catalog and command serialization
• Java light-controller tool catalog and routed-call handling, if it remains a supported control-plane runtime

Light Fabric Runtime Design

Light Fabric should provide a small cache abstraction at the runtime layer so applications do not each define a different operational surface.

A practical shape is:

#![allow(unused)]
fn main() {
#[async_trait::async_trait]
pub trait RuntimeCache: Send + Sync {
    async fn len(&self) -> usize;
    async fn entries_summary(&self) -> serde_json::Value;
    async fn clear(&self);
}

#[derive(Default)]
pub struct CacheRegistry {
    caches: RwLock<BTreeMap<String, Arc<dyn RuntimeCache>>>,
}
}

The registry should support:

• register named cache
• list cache names
• get summarized entries
• clear a named cache

moka is the preferred default backend for async Rust services because it maps well to the Caffeine use case. Applications should still be free to register custom cache wrappers as long as they implement the runtime trait.

RuntimeMcpHandler in light-runtime should expose the same tools as Java:

• list_caches
• get_cache_entries
• clear_cache

If a runtime has no cache registry, these tools should return supported: false rather than failing the request.

Portal Service Reference Data Cache

portal-service can use the generic Light Fabric cache for /r/data.

Suggested cache names:

• reference-data
• reference-data-relation

Suggested keys:

• host:{hostId|global}:lang:{lang}:table:{name}
• host:{hostId|global}:lang:{lang}:table:{name}:rela:{rela}:from:{from}

The request flow becomes:

1. /r/data receives a reference-data request.
2. ReferenceService builds a stable cache key from host, language, table, relation, and source value.
3. On cache hit, return cached reference data.
4. On cache miss, query Postgres, cache the result, and return it.
5. When reference data changes in light-portal, an operator clears reference-data or reference-data-relation for the target portal-service runtime instance from portal-view.
6. The next /r/data call reloads from Postgres.

This keeps the first implementation manual and deterministic. A later phase can subscribe to reference-table change events and clear matching caches automatically.

Portal View UX

The existing Cache Explorer page should stay the main UI.

Add a clear action for the selected cache:

• show the selected cache name
• require confirmation before clearing
• disable the button while the request is running
• call clear_cache with { runtimeInstanceId, name }
• show success or error status
• refetch cache entries after a successful clear

The UI should not require users to know whether the target service is Java or Rust. Unsupported runtimes should show the returned unsupported message.

Implementation Phases

Phase 1: Java clear support

• Add CacheManager.clear(cacheName).
• Implement it in caffeine-cache.
• Add clear_cache to portal-registry MCP tools.
• Add targeted tests for clearing while preserving the configured cache.

Phase 2: Controller and portal-view

• Add clear_cache to controller tool catalogs and command routing.
• Add the Cache Explorer clear button and confirmation.
• Verify the existing runtimeInstanceId forwarding path is reused.

Phase 3: Light Fabric generic cache

• Add a runtime cache registry and trait.
• Add moka backed cache support.
• Expose list_caches, get_cache_entries, and clear_cache from RuntimeMcpHandler.
• Add focused light-runtime tests for supported and unsupported cache cases.

Phase 4: Portal service reference data

• Register reference-data and reference-data-relation caches.
• Cache /r/data query results.
• Clear the cache from portal-view and verify the next request reloads from Postgres.

Verification

Recommended targeted checks:

mvn -q -pl cache-manager,caffeine-cache,portal-registry test
cargo test -p light-runtime
cargo check --workspace
yarn build

Use the Maven command in light-4j, the Cargo commands in light-fabric and portal-service as appropriate, and the frontend build in portal-view.

Client Configuration And Modules

Status

Brainstorming proposal for standardizing client.yml across Light Fabric runtime, framework modules, and products.

The immediate trigger is that different Rust modules currently interpret client.yml differently. For example, light-runtime reads a small top-level verifyHostname field for controller and config-server clients, while light-pingora token and SPA modules read a Java-style nested tls section. That split makes a single client.verifyHostname: false value unreliable.

This document proposes a common contract so every Rust module uses the same client.yml file and the same typed configuration model.

Purpose

client.yml should describe outbound client behavior for a running service:

• TLS trust, hostname verification, and optional client identity.
• HTTP request timeout, retry, circuit breaker, connection pool, and HTTP/2 behavior.
• OAuth 2.0 token, key, sign, dereference, and provider-selection behavior.
• Path-prefix-to-service mapping used when different downstream services use different OAuth providers.

The file should be loaded once through the runtime configuration system, registered once in the module registry with secrets masked, then shared by all modules that make outbound calls.

Compatibility Contract

The Java light-4j client.yml remains the compatibility baseline. Rust can clean up the internal model, but it should not remove behavior that Java http-client and client-config expose.

Important Java sections:

tls:
  verifyHostname: ${client.verifyHostname:true}
  loadDefaultTrustStore: ${client.loadDefaultTrustStore:true}
  loadTrustStore: ${client.loadTrustStore:true}
  trustStore: ${client.trustStore:client.truststore}
  trustStorePass: ${client.trustStorePass:password}
  loadKeyStore: ${client.loadKeyStore:false}
  keyStore: ${client.keyStore:client.keystore}
  keyStorePass: ${client.keyStorePass:password}
  keyPass: ${client.keyPass:password}
  defaultCertPassword: ${client.defaultCertPassword:changeit}
  tlsVersion: ${client.tlsVersion:TLSv1.3}

oauth:
  multipleAuthServers: ${client.multipleAuthServers:false}
  token:
    cache:
      capacity: ${client.tokenCacheCapacity:200}
    tokenRenewBeforeExpired: ${client.tokenRenewBeforeExpired:60000}
    expiredRefreshRetryDelay: ${client.expiredRefreshRetryDelay:2000}
    earlyRefreshRetryDelay: ${client.earlyRefreshRetryDelay:4000}
    server_url: ${client.tokenServerUrl:}
    serviceId: ${client.tokenServiceId:com.networknt.oauth2-token-1.0.0}
    proxyHost: ${client.tokenProxyHost:}
    proxyPort: ${client.tokenProxyPort:}
    enableHttp2: ${client.tokenEnableHttp2:true}
    authorization_code: {}
    client_credentials: {}
    refresh_token: {}
    token_exchange: {}
    key: {}
  sign: {}
  deref: {}

pathPrefixServices: ${client.pathPrefixServices:}

request:
  errorThreshold: ${client.errorThreshold:2}
  connectTimeout: ${client.connectTimeout:2000}
  timeout: ${client.timeout:3000}
  resetTimeout: ${client.resetTimeout:7000}
  injectOpenTracing: ${client.injectOpenTracing:false}
  injectCallerId: ${client.injectCallerId:false}
  enableHttp2: ${client.enableHttp2:true}
  connectionPoolSize: ${client.connectionPoolSize:1000}
  connectionExpireTime: ${client.connectionExpireTime:1800000}
  maxReqPerConn: ${client.maxReqPerConn:1000000}
  maxConnectionNumPerHost: ${client.maxConnectionNumPerHost:1000}
  minConnectionNumPerHost: ${client.minConnectionNumPerHost:250}
  maxRequestRetry: ${client.maxRequestRetry:3}
  requestRetryDelay: ${client.requestRetryDelay:1000}
  poolMetricsEnabled: ${client.poolMetricsEnabled:false}
  poolWarmUpEnabled: ${client.poolWarmUpEnabled:false}
  poolWarmUpSize: ${client.poolWarmUpSize:1}
  healthCheckEnabled: ${client.healthCheckEnabled:true}
  healthCheckIntervalMs: ${client.healthCheckIntervalMs:30000}

Rust should add fields such as tls.caCertPath, tls.clientCertPath, and tls.clientKeyPath because PEM files are the native Rust deployment shape. Rust does not need to support Java-specific JKS/JCEKS truststore or keystore formats. If those Java-only fields appear in a Rust client.yml, they can be ignored because config-server should control which fields it injects for Rust services.

Initial Rust Gaps

At the start of this migration, the Rust implementation had three separate interpretations of client configuration:

Before this design, Rust support was also partial compared with Java:

Goals

• Keep client.yml as the only config file for outbound client behavior.
• Make the Java nested shape canonical: tls.verifyHostname, not top-level verifyHostname.
• Load and register the resolved client.yml once through light-runtime.
• Share one typed ClientConfig across runtime, Pingora, gateway, agent, deployer, MCP clients, model-provider clients, and future products.
• Preserve Java-compatible field names and config-server placeholder names.
• Support direct URL, direct registry, and portal registry service discovery consistently for token, key, sign, deref, and generic outbound calls.
• Keep secrets masked in module registry snapshots and logs.
• Make invalid active client config fail startup or reject reload before it changes live runtime behavior.
• Allow Rust-native PEM fields without forcing Java keystore names into every Rust deployment.

Non-Goals

• Do not move handler activation into client.yml. Handler-specific files such as token.yml, statelessAuth.yml, and msal-exchange.yml still decide whether a handler runs.
• Do not implement every Java-only low-level connection-pool behavior in the first phase. The shared schema should include the fields so config is not lost, but unsupported fields can be ignored deliberately until the transport supports them.
• Do not expose decrypted client secrets, tokens, or legacy Java password fields through module registry, MCP tools, logs, metrics, or cache output.
• Do not require every module to use OAuth. The shared config must support simple TLS-only clients too.

Resolved Decisions

• Create a separate light-client crate now so the shared config, HTTP client factory, OAuth client, and provider resolver can be reused without coupling every consumer to light-runtime.
• Standardize Rust outbound TLS material on PEM paths. Java truststore and keystore formats are not required for Rust services.
• client.yml reload should not force an immediate portal-registry reconnect. Reload is primarily for newly onboarded JWKS/JWT access and future outbound requests. Existing long-lived controller connections can keep running until their normal reconnect or service restart.
• Unsupported Java fields can be ignored by Rust. Config-server should avoid injecting unsupported fields into Rust service config.
• Ignored Java-only fields should be ignored silently. Rust startup does not need to warn about fields that config-server may omit for Rust services.
• oauth.multipleAuthServers remains accepted for Java compatibility, but Rust should infer multi-provider mode when serviceIdAuthServers is configured.
• pathPrefixServices stays in client.yml. It is outbound-client provider selection and is different from inbound path routing to downstream services.
• Circuit breaker behavior is only needed by Pingora. Shared request config can carry the Java-compatible fields, but non-Pingora clients do not need to own circuit breaker state.
• SAML bearer is not required for Light Fabric and should remain out of scope unless a future product explicitly needs it.

Proposed Canonical Shape

The canonical Rust client.yml should stay close to Java:

tls:
  verifyHostname: ${client.verifyHostname:true}
  caCertPath: ${client.caCertPath:}
  clientCertPath: ${client.clientCertPath:}
  clientKeyPath: ${client.clientKeyPath:}
  tlsVersion: ${client.tlsVersion:TLSv1.3}

request:
  connectTimeout: ${client.connectTimeout:2000}
  timeout: ${client.timeout:3000}
  maxRequestRetry: ${client.maxRequestRetry:3}
  requestRetryDelay: ${client.requestRetryDelay:1000}
  errorThreshold: ${client.errorThreshold:2}
  resetTimeout: ${client.resetTimeout:7000}
  injectCallerId: ${client.injectCallerId:false}
  enableHttp2: ${client.enableHttp2:true}
  connectionPoolSize: ${client.connectionPoolSize:1000}
  connectionExpireTime: ${client.connectionExpireTime:1800000}
  maxReqPerConn: ${client.maxReqPerConn:1000000}
  maxConnectionNumPerHost: ${client.maxConnectionNumPerHost:1000}
  minConnectionNumPerHost: ${client.minConnectionNumPerHost:250}
  poolMetricsEnabled: ${client.poolMetricsEnabled:false}
  poolWarmUpEnabled: ${client.poolWarmUpEnabled:false}
  poolWarmUpSize: ${client.poolWarmUpSize:1}
  healthCheckEnabled: ${client.healthCheckEnabled:true}
  healthCheckIntervalMs: ${client.healthCheckIntervalMs:30000}

oauth:
  multipleAuthServers: ${client.multipleAuthServers:false}
  token:
    cache:
      capacity: ${client.tokenCacheCapacity:200}
    tokenRenewBeforeExpired: ${client.tokenRenewBeforeExpired:60000}
    expiredRefreshRetryDelay: ${client.expiredRefreshRetryDelay:2000}
    earlyRefreshRetryDelay: ${client.earlyRefreshRetryDelay:4000}
    server_url: ${client.tokenServerUrl:}
    serviceId: ${client.tokenServiceId:com.networknt.oauth2-token-1.0.0}
    proxyHost: ${client.tokenProxyHost:}
    proxyPort: ${client.tokenProxyPort:}
    enableHttp2: ${client.tokenEnableHttp2:true}
    authorization_code:
      uri: ${client.tokenAcUri:/oauth2/token}
      client_id: ${client.tokenAcClientId:}
      client_secret: ${client.tokenAcClientSecret:}
      redirect_uri: ${client.tokenAcRedirectUri:}
      scope: ${client.tokenAcScope:}
    client_credentials:
      uri: ${client.tokenCcUri:/oauth2/token}
      client_id: ${client.tokenCcClientId:}
      client_secret: ${client.tokenCcClientSecret:}
      scope: ${client.tokenCcScope:}
      serviceIdAuthServers: ${client.tokenCcServiceIdAuthServers:}
    refresh_token:
      uri: ${client.tokenRtUri:/oauth2/token}
      client_id: ${client.tokenRtClientId:}
      client_secret: ${client.tokenRtClientSecret:}
      scope: ${client.tokenRtScope:}
    token_exchange:
      uri: ${client.tokenExUri:/oauth2/token}
      client_id: ${client.tokenExClientId:}
      client_secret: ${client.tokenExClientSecret:}
      scope: ${client.tokenExScope:}
      subjectToken: ${client.subjectToken:}
      subjectTokenType: ${client.subjectTokenType:urn:ietf:params:oauth:token-type:jwt}
      requestedTokenType: ${client.requestedTokenType:}
      audience: ${client.tokenExAudience:}
    key:
      server_url: ${client.tokenKeyServerUrl:}
      serviceId: ${client.tokenKeyServiceId:com.networknt.oauth2-key-1.0.0}
      uri: ${client.tokenKeyUri:/oauth2/key}
      client_id: ${client.tokenKeyClientId:}
      client_secret: ${client.tokenKeyClientSecret:}
      enableHttp2: ${client.tokenKeyEnableHttp2:true}
      serviceIdAuthServers: ${client.tokenKeyServiceIdAuthServers:}
      audience: ${client.tokenKeyAudience:}
  sign:
    server_url: ${client.signServerUrl:}
    serviceId: ${client.signServiceId:com.networknt.oauth2-token-1.0.0}
    uri: ${client.signUri:/oauth2/sign}
    timeout: ${client.signTimeout:2000}
    client_id: ${client.signClientId:}
    client_secret: ${client.signClientSecret:}
    proxyHost: ${client.signProxyHost:}
    proxyPort: ${client.signProxyPort:}
    enableHttp2: ${client.signEnableHttp2:true}
    key:
      server_url: ${client.signKeyServerUrl:}
      serviceId: ${client.signKeyServiceId:com.networknt.oauth2-key-1.0.0}
      uri: ${client.signKeyUri:/oauth2/key}
      client_id: ${client.signKeyClientId:}
      client_secret: ${client.signKeyClientSecret:}
      enableHttp2: ${client.signKeyEnableHttp2:true}
      audience: ${client.signKeyAudience:}
  deref:
    server_url: ${client.derefServerUrl:}
    serviceId: ${client.derefServiceId:com.networknt.oauth2-token-1.0.0}
    uri: ${client.derefUri:/oauth2/deref}
    client_id: ${client.derefClientId:}
    client_secret: ${client.derefClientSecret:}
    proxyHost: ${client.derefProxyHost:}
    proxyPort: ${client.derefProxyPort:}
    enableHttp2: ${client.derefEnableHttp2:true}

pathPrefixServices: ${client.pathPrefixServices:}

Compatibility aliases:

• Accept serverUrl in addition to Java server_url for Rust callers.
• Accept clientId and clientSecret in addition to Java client_id and client_secret only as aliases. The emitted template should keep Java names.
• Temporarily accept top-level verifyHostname only as a migration fallback, but register a warning and normalize it into tls.verifyHostname.

Serde strategy for the top-level verifyHostname fallback:

• The shared ClientConfig should deserialize into a struct that has a tls.verifyHostname field and a separate #[serde(default)] top-level verify_hostname field.
• After deserialization, a post-parse normalization step should check whether the top-level field was explicitly set. If so, it logs a deprecation warning and copies the value into tls.verify_hostname only when the nested field was not also explicitly set.
• When both the top-level and nested fields are present, the nested tls.verifyHostname value wins. The top-level value is ignored after the warning.
• Do not rely on two competing #[serde(default)] fields resolving the conflict. Use a custom Deserialize impl or an explicit post-parse step.

Serde strategy for Java-compatible but unimplemented sections:

• Do not use #[serde(deny_unknown_fields)] for the top-level ClientConfig or OAuth section during Phase 1.
• Known but not-yet-implemented Java sections such as oauth.sign and oauth.deref should deserialize into typed structs or serde_json::Value placeholders so representative Java fixtures load successfully.
• Demand-driven validation decides whether a section is required. If no active module consumes oauth.sign or oauth.deref, those sections can be present and ignored silently.

Proposed Rust Modules

Shared Config Model

Create one shared typed config model outside light-pingora and light-runtime:

crates/light-client/src/lib.rs
crates/light-client/src/config.rs
crates/light-client/src/http.rs
crates/light-client/src/oauth.rs
crates/light-client/src/provider.rs

light-runtime should use light-client for loading, validating, and building outbound clients, but the reusable client model should not live inside the runtime crate.

Core types:

#![allow(unused)]
fn main() {
pub struct ClientConfig {
    pub tls: ClientTlsConfig,
    pub request: ClientRequestConfig,
    pub oauth: ClientOauthConfig,
    pub path_prefix_services: BTreeMap<String, String>,
}

pub struct ClientTlsConfig {
    pub verify_hostname: bool,
    pub ca_cert_path: Option<PathBuf>,
    pub client_cert_path: Option<PathBuf>,
    pub client_key_path: Option<PathBuf>,
    pub tls_version: Option<TlsVersion>,
}

pub struct ClientRequestConfig {
    pub connect_timeout_ms: u64,
    pub timeout_ms: u64,
    pub max_request_retry: u32,
    pub request_retry_delay_ms: u64,
    pub error_threshold: u32,
    pub reset_timeout_ms: u64,
    pub inject_caller_id: bool,
    pub enable_http2: bool,
    pub pool: ClientPoolConfig,
}
}

TlsVersion should be an enum with serde names for Java-compatible strings such as TLSv1.2 and TLSv1.3, rather than a raw string in runtime code.

Secrets should use a type that serializes as masked data for registry output, or the registry masks should cover every secret field recursively.

Runtime Loader

light-runtime should own the startup lifecycle for client.yml loading, but delegate parsing and validation to light-client:

1. Load local values.yml.
2. Load local startup.yml.
3. Load local client.yml with resolved values for config-server bootstrap.
4. Fetch remote config if configured.
5. Rebuild the final RuntimeConfig with the remote client.yml overlay.
6. Register masked light-client/client in ModuleRegistry.

Every runtime client should use this shared config:

• config-server fetch client
• portal-registry WebSocket client
• MCP client
• future model-provider outbound clients
• framework/application clients through RuntimeConfig.client

For the earlier hostname-verification bug, the controller client should read:

runtime_config.client.tls.verify_hostname

not a separate top-level ClientConfig.verify_hostname.

HTTP Client Factory

Add a small factory that converts ClientConfig plus optional per-endpoint overrides into concrete clients:

#![allow(unused)]
fn main() {
pub struct ClientFactory {
    config: Arc<ClientConfig>,
    direct_registry: DirectRegistryConfig,
    registry_client: Option<Arc<PortalRegistryClient>>,
}

pub struct EndpointOptions {
    pub server_url: Option<String>,
    pub service_id: Option<String>,
    pub proxy_host: Option<String>,
    pub proxy_port: Option<u16>,
    pub enable_http2: Option<bool>,
    pub timeout_ms: Option<u64>,
}
}

Responsibilities:

• Build reqwest::Client with consistent TLS, timeout, proxy, HTTP/2, retry, and pool settings for non-Pingora consumers.
• Build Pingora HttpPeer options from the same TLS config for gateway upstream proxying.
• Resolve endpoint base URL by priority:
  1. direct server_url
  2. direct-registry.yml
  3. portal-registry discovery by serviceId
• Apply per-service AuthServerConfig overrides without duplicating resolver logic in each handler.

The config-server bootstrap path still starts from BootstrapConfig because it needs enough client settings before remote client.yml has been fetched. To keep light-client independent from light-runtime, the factory should not take a BootstrapConfig type directly. Instead, light-runtime should adapt BootstrapConfig.connect_timeout, BootstrapConfig.timeout, authorization, and bootstrap CA path into EndpointOptions or a small bootstrap options type owned by light-client.

OAuth Client

Add a shared OAuth client module that implements Java http-client behavior:

oauth/client_credentials
oauth/authorization_code
oauth/refresh_token
oauth/token_exchange
oauth/key
oauth/sign
oauth/deref

The existing light-pingora SpaTokenClient, token handler client credentials code, and security JWKS fetcher should delegate to this shared module. Handler modules still own request-path decisions, cookies, headers, and rejection mapping.

OAuth provider selection should be one reusable resolver:

#![allow(unused)]
fn main() {
pub struct OAuthProviderResolver {
    client: Arc<ClientConfig>,
}

impl OAuthProviderResolver {
    pub fn service_for_path(&self, path: &str) -> Option<&str>;
    pub fn client_credentials_provider(&self, service_id: Option<&str>) -> Result<AuthServerConfig>;
    pub fn key_provider(&self, service_id: Option<&str>) -> Result<AuthServerConfig>;
}
}

Rules:

• Single-provider mode uses global oauth.token.* defaults.
• Multi-provider mode is enabled when oauth.multipleAuthServers: true or when relevant serviceIdAuthServers maps are non-empty.
• Multi-provider mode selects the service id from an explicit request header first, then outbound pathPrefixServices.
• client_credentials.serviceIdAuthServers[serviceId] selects the token provider.
• key.serviceIdAuthServers[serviceId] selects the JWKS/key provider.
• Per-service config inherits unset values from global oauth.token defaults.
• Path-prefix matching should be boundary-aware in Rust. Java uses startsWith; the Rust implementation can be stricter as an intentional improvement. Exact rule: a prefix matches when the request path equals the prefix or starts with prefix + "/". Therefore /api matches /api and /api/orders, but does not match /api-v2.
• pathPrefixServices is not an inbound routing table. It maps outbound request paths to service ids only for client-side OAuth provider selection.

Consumer Modules

All modules should consume the same shared config:

Reload Behavior

client.yml should be reloadable as a module, but reload must be conservative:

1. Load and validate the new config into a fresh ClientConfig.
2. Build new shared client factories and OAuth clients.
3. Swap the config atomically for future requests.
4. Clear OAuth token caches because client credentials, scopes, providers, or trust settings may have changed.
5. Keep old in-flight requests on their existing client instances.
6. Reject the reload if active modules cannot build required clients from the new config.

Reload atomicity: all runtimes that consume client.yml must be swapped together in the same reload callback. Today, the gateway TokenReloader already rebuilds token_runtime, stateless_auth, and msal_exchange as a unit. This must remain a hard requirement. A reload that updates the client config without also rebuilding dependent runtimes would leave stale TLS or OAuth state in the old runtime instances.

Controller registration is long-lived. Reloading client.yml should not force an immediate portal-registry reconnect. New TLS and request settings should apply to future outbound clients and the next normal controller reconnect, but the active controller WebSocket can remain open.

Validation Rules

Base validation:

• tls.verifyHostname: false requires explicit trust material unless the transport has a clear dev-only mode.
• If Rust-native mTLS is configured, both client certificate and client key paths are required.
• request.connectTimeout and request.timeout must be positive.
• proxyPort must be 0 to 65535.
• pathPrefixServices keys must start with /.
• Secret fields may be empty only when the consuming active module does not need that grant.

OAuth validation should be demand-driven:

• If token handler is active and enabled, validate client_credentials.
• If stateless-auth is active, validate authorization_code and refresh_token.
• If msal-exchange is active, validate token_exchange.
• If security.yml enables JWKS bootstrap from key service, validate oauth.token.key.
• If a future sign module is active, validate oauth.sign.
• If a future deref module is active, validate oauth.deref.

This avoids forcing every service to configure every Java OAuth section.

Validation failure behavior:

• At startup, validation failures are fatal. The process must exit with a clear error message identifying which active module requires which missing or invalid client config section.
• On reload, validation failures are non-fatal. The reload is rejected, the old config stays live, and the rejection reason is logged and reported through the module registry reload outcome.

Masking

Mask these fields recursively in registry output:

• client_secret
• clientSecret
• trustStorePass
• keyStorePass
• keyPass
• defaultCertPassword
• subjectToken
• access_token
• refresh_token
• id_token
• authorization
• any field ending in Token whose value is a scalar string (not a nested object, list, or URN-typed field like subjectTokenType or requestedTokenType)
• any field ending in Secret

Explicit exclusions from suffix matching:

• subjectTokenType - a URN string, not a secret.
• requestedTokenType - a URN string, not a secret.

The registry should store only the masked snapshot. It should not store raw config and mask later.

Migration Plan

Phase 0: Deprecation Logging

• Add a tracing::warn! in light-gateway where it reads resolved_values["client.verifyHostname"] to alert operators that this path is deprecated and will be replaced by runtime_config.client.tls.verify_hostname.
• This gives operators visibility into the migration before behavior changes.

Phase 1: Unify The Schema

• Add the light-client crate with the full shared ClientConfig type.
• Make light-runtime load nested tls.verifyHostname.
• Keep top-level verifyHostname as a temporary compatibility fallback.
• Update Rust config templates to include only the canonical nested shape.
• Add tests proving client.verifyHostname: false reaches config-server, portal-registry, token, security JWKS, SPA auth, and gateway proxy clients.

Phase 2: Move Consumers To Shared Config

• Replace light-pingora::token::ClientTokenConfig with the light-client shared type or a type alias.
• Replace gateway direct resolved_values["client.verifyHostname"] lookup with runtime_config.client.tls.verify_hostname.
• Move JWKS, token, and SPA token HTTP client construction behind the shared client factory.
• Register one masked light-client/client module instead of separate partial client registry entries.

Phase 3: Shared OAuth Provider Resolver

• Extract provider selection from the token handler.
• Support token.key.serviceIdAuthServers and audience.
• Use the same resolver for token injection and JWT key lookup.
• Keep Java field names and config-server placeholders.

Phase 4: Java Feature Completion

• Implemented sign client support in light-client.
• Implemented deref client support in light-client.
• Implemented Rust-native PEM mTLS for reqwest clients and Pingora upstreams.
• Implemented retry, circuit breaker, and pool behavior where the Rust transport supports them.

Open Questions

None at this stage.

Test Plan

Unit tests:

• Parse the Java client.yml template into the shared Rust config.
• Parse the current Rust client.yml template into the shared Rust config.
• Resolve client.verifyHostname into tls.verifyHostname.
• Accept top-level verifyHostname only as a fallback and prefer nested TLS when both are set.
• Mask every secret field in the module registry snapshot.
• Validate provider selection by service id and path prefix.
• Validate per-service override inheritance for token and key providers.

Runtime tests:

• Config-server bootstrap uses tls.verifyHostname.
• Portal-registry controller WebSocket uses tls.verifyHostname.
• Gateway upstream proxy uses tls.verifyHostname.
• Token handler, stateless auth, MSAL exchange, and security JWKS all receive the same ClientConfig instance or snapshot.
• Client reload clears token caches and rejects invalid active grant config.
• Reload round-trip: verify that reloading from config A to config B swaps the ClientConfig, creates fresh token caches, and that in-flight requests on the old config are not affected. Verify that a reload from valid config to invalid config is rejected and the old config stays live.

Compatibility tests:

• Reuse representative Java client.yml fixtures for single provider, multiple providers, proxy, token key, sign, and deref sections.
• Confirm Java-compatible form bodies for authorization_code, client_credentials, refresh_token, and token_exchange.
• Confirm config-server injected YAML strings and structured YAML maps both deserialize for serviceIdAuthServers and pathPrefixServices.

Embedded Configuration Templates

Status

Initial implementation completed. Rust applications in light-fabric and related portal-service applications keep template configuration files under each app's config directory. Container images may copy those files into /app/config-defaults, then runtime overlays local config, downloaded config-cache, remote values.yml, and environment variables.

That works well for container deployments. It is awkward for native binary deployments on a VM because the operator must copy a full template directory beside the binary even when they only want to provide values.yml, certs, or a small local override.

This design embeds the template files into the Rust binary while keeping the app config directories in source control as the readable template source.

Purpose

Embedded configuration templates should make the Rust deployment model match the Java module model more closely:

1. The application binary carries its default template files.
2. Operators provide only overrides, usually values.yml, startup.yml, certs, keys, or environment variables.
3. Config-server can still return values.yml after bootstrap, plus external files for explicit migration or operational exceptions.
4. Developers and operators can still inspect the app's config directory in source control to learn supported properties.

The embedded files are defaults. They are not runtime state and should not be written out automatically unless an explicit diagnostic/export command is added later.

Current Model

The current runtime model has these filesystem layers:

For light-fabric runtime applications, LightRuntimeBuilder passes default_config_dir, config_dir, and external_config_dir into light-runtime. load_bootstrap_config() reads bootstrap-time values.yml, startup.yml, and client.yml before remote config-server bootstrap. After remote bootstrap, runtime config loads server.yml, client.yml, portal-registry.yml, and framework/application module files through the same merged configuration path.

Some portal-service apps share the light-runtime path, while standalone apps such as config-server and light-oauth have local helper functions that merge config-defaults and config.

Goals

• Allow a native binary deployment to start with embedded templates and a small external config/values.yml.
• Keep apps/<app>/config/*.yml as the source of truth for template content.
• Keep container deployment behavior compatible with the current /app/config-defaults copy.
• Preserve the existing overlay order and placeholder expansion behavior.
• Support bootstrap-time files such as startup.yml and client.yml.
• Support runtime module files such as handler.yml, proxy.yml, model-provider.yml, provider configs, and product-specific files.
• Provide one reusable loading abstraction for light-fabric and portal-service instead of app-specific parsing logic.
• Avoid writing embedded templates to disk during normal startup.

Non-Goals

• Do not embed secrets, certificates, private keys, trust bundles, static web assets, or downloaded config-server files.
• Do not remove the source config directories. They remain the reviewable, documented template source.
• Do not make values.yml mandatory. Apps should keep current defaults where they are already valid.
• Do not make config-server responsible for delivering template files that are already part of the binary.
• Do not change the meaning of values.yml placeholders or environment variable expansion.

Proposed Layer Order

The new effective source order should be:

1. Embedded template file from the binary.
2. Filesystem default template from config-defaults, if present.
3. Local operator file from config.
4. External/cache file from config-cache, when runtime loading supports it.
5. Remote values.yml payload from config-server.
6. Environment variables during placeholder resolution.

This keeps existing container images compatible. If config-defaults exists, it can override the embedded template. That gives operators and image builders a transition path and a deliberate escape hatch for patched images.

For native binary deployment, config-defaults is simply absent and the binary falls back to embedded templates.

Structured config files and values.yml should use different overlay semantics:

After the structured file source is selected, placeholders in that file are resolved from the merged values map and environment variables.

Embedded Template Representation

include_dir is a possible embedding mechanism. It embeds the entire app config directory at compile time and avoids custom directory-scanning build scripts in every application crate:

#![allow(unused)]
fn main() {
use include_dir::{include_dir, Dir};

pub static EMBEDDED_CONFIG: Dir<'_> = include_dir!("$CARGO_MANIFEST_DIR/config");
}

The runtime should hide the concrete embedding mechanism behind a small config source abstraction. A typed file representation is still useful as the stable runtime boundary:

#![allow(unused)]
fn main() {
pub struct EmbeddedConfigFile {
    pub name: &'static str,
    pub content: &'static str,
}
}

Application code should pass a flattened static file list into the runtime:

#![allow(unused)]
fn main() {
LightRuntimeBuilder::new(transport)
    .with_embedded_config(embedded_config::FILES)
    .build();
}

include_str! is still acceptable for one or two files, but application main.rs files should not accumulate hand-maintained include_str! lists. include_bytes! is not preferred for YAML templates because configuration templates should be valid UTF-8 before they are parsed.

The initial implementation uses a shared build-time generator instead of adding an external embedding dependency. Each app has a small build.rs that calls config-embed-build, which scans the committed config directory and produces a manifest like this under OUT_DIR:

#![allow(unused)]
fn main() {
pub const FILES: &[config_loader::EmbeddedConfigFile] = &[
    config_loader::EmbeddedConfigFile {
        name: "server.yml",
        content: include_str!(concat!(env!("CARGO_MANIFEST_DIR"), "/config/server.yml")),
    },
    config_loader::EmbeddedConfigFile {
        name: "startup.yml",
        content: include_str!(concat!(env!("CARGO_MANIFEST_DIR"), "/config/startup.yml")),
    },
];
}

Build-Time Generation Fallback

The project currently uses the build-time manifest path. Each app uses a shared build.rs helper to scan its config directory and generate the embedded manifest. The generator lives in one reusable crate so apps do not carry duplicated build logic.

The generated manifest should:

• Include only known text config extensions, initially .yml, .yaml, .json, and .toml.
• Preserve the file name relative to the app config directory.
• Emit cargo:rerun-if-changed=config.
• Fail the build if a template file cannot be read as UTF-8.

Nested config paths are not needed for current app templates, but the manifest should allow names such as oauth/server.yml if a future product needs them.

Runtime API

Add embedded defaults to LightRuntimeBuilder:

#![allow(unused)]
fn main() {
LightRuntimeBuilder::new(transport)
    .with_embedded_config(embedded_config::FILES)
    .with_default_config_dir(DEFAULT_CONFIG_DIR)
    .with_config_dir(CONFIG_DIR)
    .with_external_config_dir(EXTERNAL_CONFIG_DIR)
    .build();
}

RuntimeConfig should carry the embedded source as skipped runtime state, the same way it carries default_config_dir and registries today:

#![allow(unused)]
fn main() {
pub struct RuntimeConfig {
    // existing fields
    #[serde(skip, default)]
    pub embedded_config: &'static [EmbeddedConfigFile],
}
}

The stable contract is lookup by relative file name and iteration for diagnostics or dumping. The concrete representation can remain a static file slice or later move behind a provider abstraction if needed.

The low-level loader should accept named in-memory content as another config source:

#![allow(unused)]
fn main() {
pub enum ConfigSource {
    Embedded { name: &'static str, content: &'static str },
    File(PathBuf),
}
}

ConfigLoader can then parse embedded and filesystem sources with the same YAML/JSON/TOML parser. Structured config loading should select the highest priority source for the requested file. values.yml loading should continue to merge maps in source order.

Bootstrap Behavior

Bootstrap must support embedded templates because this is the path that native deployments need most.

load_bootstrap_values() should merge:

1. Embedded values.yml, if present.
2. config-defaults/values.yml, if present.
3. config/values.yml, if present.

load_bootstrap_config() should load startup.yml and client.yml from:

1. Embedded templates.
2. config-defaults.
3. config.

For startup.yml and client.yml, the highest-priority source that contains the file should be used as the full template. Placeholder resolution still uses the merged bootstrap values.

After bootstrap fetches remote values, load_values_map() should merge embedded values.yml before the existing file and remote layers. This allows remote values to override embedded placeholders exactly as they override copied template files today.

Application Integration

Light-Gateway

light-gateway should be the first light-fabric application to adopt the runtime API because it has the richest template set:

• bootstrap and server files
• client and portal registry files
• handler chain files
• proxy, resource, MCP, websocket, auth, token, metrics, and rule-related files

After integration, a native gateway deployment can run with the binary plus a small config/values.yml and any required cert/key files.

Light-Agent

light-agent should use the same runtime API for all provider templates. The embedded set should include model-provider.yml, mcp-client.yml, and every provider-specific template such as openai.yml, bedrock.yml, codex.yml, anthropic.yml, and ollama.yml.

Runtime provider selection should still happen after bootstrap. Embedded templates do not mean provider clients are created before config-server values are loaded.

Light-Deployer

light-deployer currently has a separate app-level config load for deployer.yml. It should either move to the shared embedded-source helper or set embedded defaults on LightRuntimeBuilder and use the same merged source logic for its application config.

Portal-Service App

portal-service/apps/portal-service already uses LightRuntimeBuilder, but it loads portal-service.yml before runtime startup to create the database pool. That pre-runtime load should use the same shared embedded-source helper.

The portal-service.yml config remains non-reloadable because dbUrl and hostId feed process-owned state.

Portal-Service Config-Server And Light-OAuth

portal-service/apps/config-server and apps/light-oauth do not bootstrap from config-server. They should still embed their server.yml templates so native deployment does not require a copied config-defaults directory.

Because these apps have local merge helpers today, they should consume a shared config-loader helper that can merge:

1. Embedded defaults.
2. Filesystem defaults.
3. Local config.

This keeps their behavior aligned with light-runtime without requiring them to become runtime-bootstrap applications.

Operator Model

For a native deployment, the recommended layout becomes:

/opt/light-gateway/
  light-gateway
  config/
    values.yml
    startup.yml        # optional, only when values/env defaults are not enough
    cert.pem           # optional external asset
    key.pem            # optional external asset

The operator no longer needs to copy every template file beside the binary. They only provide files that are deployment-specific.

For a container deployment, the current layout continues to work:

/app/light-gateway
/app/config-defaults/*.yml
/config/values.yml
/app/config-cache/values.yml

In the long term, the /app/config-defaults copy can become optional. Keeping it during migration is useful because it lets operators inspect templates inside the image and provides a familiar override layer.

After embedded templates are stable across production deployments, Docker images should deprecate and then remove the unconditional /app/config-defaults copy. Template inspectability should move to explicit dump/print commands rather than extra image layers.

Diagnostics

The runtime should expose enough information to make source precedence clear:

• Log whether embedded templates were registered for the application.
• When a required config file is missing, include the searched source names: embedded, config-defaults, config, and config-cache.
• Module registry snapshots should show the resolved config, not the raw embedded template.
• Module registry metadata should include config source provenance when available, for example embedded, file:/app/config-defaults/server.yml, or file:/config/server.yml.
• Normal startup should not write embedded templates to disk.

Native operators should have explicit inspection commands:

light-gateway --print-default-config server.yml
light-gateway --dump-default-configs ./config-defaults

The print command writes one embedded template to stdout. The dump command writes all embedded templates to a target directory so operators can inspect, copy, and customize them.

Controller Server Info Compatibility

Rust services register with the controller, and the controller can call the runtime MCP service-info path to inspect runtime configuration. This behavior must continue to work with embedded templates.

The service-info response should expose resolved runtime configuration, not raw templates. The implementation contract is:

1. Select the effective structured config source, such as embedded server.yml, filesystem config/server.yml, or cached config-cache server.yml.
2. Build the merged values map from embedded, filesystem, cached, remote values.yml, and environment variables.
3. Resolve placeholders in the selected config source.
4. Deserialize the resolved config into the typed runtime or module config.
5. Register that typed config in ModuleRegistry.
6. Return ModuleRegistry component configs from the controller service-info MCP call.

With that flow, the controller still sees every registered config file with defaults and overrides applied. Embedded templates only replace the missing filesystem default-template layer. They should not bypass typed config loading, masking, module registration, reload validation, or service-info reporting.

Source provenance can be added as metadata beside each registered config, but it must not replace the resolved config payload that operators and the controller depend on.

Testing Strategy

Add unit tests at the shared loader boundary:

• Embedded-only server.yml loads successfully.
• Local config/server.yml replaces embedded server.yml rather than deep merging with it.
• config-defaults/server.yml replaces embedded server.yml.
• config-cache/server.yml replaces local config during runtime loads.
• Embedded values.yml is overridden by local values.yml.
• Remote values.yml overrides embedded and filesystem values.
• Missing required config reports all searched layers.
• Source provenance is recorded for resolved module configs.
• --print-default-config and --dump-default-configs expose embedded templates without changing normal startup behavior.
• Controller service-info output includes resolved values from embedded defaults plus local, cached, remote, and environment overrides.

Add application-level smoke tests for:

• light-gateway startup with no filesystem server.yml, using embedded templates plus local values.yml.
• light-agent provider config loading from embedded templates after bootstrap.
• portal-service/apps/portal-service pre-runtime portal-service.yml load from embedded templates.
• portal-service/apps/config-server standalone server.yml load from embedded templates.

Migration Plan

1. Add embedded source support to config-loader and light-runtime.
2. Add shared build-time template embedding for light-gateway.
3. Wire light-gateway to pass embedded templates to LightRuntimeBuilder.
4. Keep Docker config-defaults copies unchanged and verify container parity.
5. Add native startup tests that run without a copied template directory.
6. Roll the same pattern to light-agent and light-deployer.
7. Add the shared embedded-source helper to portal-service and migrate portal-service, config-server, and light-oauth.
8. Add print and dump commands for embedded templates.
9. After several releases, deprecate Docker config-defaults copies and rely on embedded defaults plus explicit dump commands for inspectability.

Risks And Mitigations

Resolved Decisions

• Native operators should get --print-default-config <name> and --dump-default-configs <directory> commands.
• Module registry should expose resolved config first, with source provenance as metadata when available.
• Docker images should keep /app/config-defaults during migration, then deprecate it once embedded templates and dump commands are stable.
• Rust deployments should standardize on embedded templates plus remote values.yml. Config-server should not normally deliver full template files for Rust services.

Decision Summary

Embed app config/*.yml templates into the binary as the lowest-priority default configuration source. The initial implementation uses a shared build-time manifest generator, with include_dir remaining a possible future implementation detail. Keep the existing source config directories for documentation and build input. Use source-level override for structured config files and key-level overlay for values.yml. Preserve current filesystem and remote value layers so container deployments keep working, while native deployments can run with only the binary and a small deployment-specific config directory.

Handler Chain

Status: Phases 1, 2, 3, 4, 5, 6, 7, and 8 implemented; further transport phases proposed

Purpose

Light Fabric needs a light-pingora handler chain for the Rust light-gateway product.

The first implementation should focus on light-pingora, not a generic cross-framework abstraction. A Pingora-first design is simpler and matches the gateway family of use cases: gateway, sidecar, proxy server, proxy client, load balancer, and BFF.

The deployment model should use one light-gateway binary. Different runtime behaviors should come from product-specific configuration managed in light-portal and delivered by config-server. A BFF deployment, a sidecar deployment, and a load-balancer deployment can therefore run the same binary with different handler.yml, traffic/resource config, and handler-specific config files.

The design should preserve the useful part of light-4j handler.yml: ordered configuration of cross-cutting request and response concerns. It should not copy the Java reflection model, mutable next handler pattern, or class-name-based configuration.

Goals

• Add middleware handler-chain support to frameworks/light-pingora.
• Use one apps/light-gateway binary for the Pingora gateway family.
• Keep handler.yml as the chain and ordering configuration.
• Let light-portal manage product-specific configuration and config-server deliver it at startup.
• Support virtual hosts selected from the HTTP Host header.
• Serve static SPA content directly from Pingora.
• Proxy API, BFF, sidecar, and balancer routes to upstream services.
• Use stable handler IDs instead of Rust type names.
• Use explicit handler registration. Do not require inventory.
• Integrate loaded handler and traffic/resource config with ModuleRegistry.
• Keep the design compatible with runtime config reload.

Non-Goals

• Do not build a transport-neutral light-handler crate in the first phase.
• Do not add an Axum/Tower adapter in the first phase.
• Do not create separate binaries for gateway, sidecar, proxy server, proxy client, load balancer, and BFF in the first phase.
• Do not dynamically load handler crates from handler.yml.
• Do not use Java-style reflection or string-to-type construction.
• Do not make Rust type names part of the public config contract.
• Do not support multi-certificate TLS SNI selection in the first phase.
• Do not implement streaming static-file delivery in the first phase unless it is needed for a concrete SPA asset size problem.

Current Shape

light-pingora already adapts a Pingora proxy into the shared runtime:

#![allow(unused)]
fn main() {
pub trait PingoraApp: Send + Sync + 'static {
    type Proxy: ProxyHttp + Send + Sync + 'static;

    fn proxy(&self, config: &RuntimeConfig) -> Result<Self::Proxy, RuntimeError>;
}
}

PingoraTransport calls app.proxy(config) and passes the result to pingora::proxy::http_proxy_service(...).

Pingora's ProxyHttp lifecycle already has the hooks needed for the gateway family:

• request_filter: validate, authenticate, rate limit, or directly write a local response such as a static file
• upstream_peer: select the upstream for proxy routes
• upstream_request_filter: mutate the request sent to upstream
• upstream_response_filter: mutate the upstream response before caching
• response_filter: mutate the response sent to the browser

The current light-gateway already writes /health directly from request_filter. Static SPA serving can use the same pattern.

Product Model

The Rust light-gateway binary should link all built-in Pingora gateway capabilities:

• virtual host routing
• static SPA serving
• reverse proxy routing
• outbound proxy behavior
• upstream load balancing
• sidecar token/header behavior
• shared middleware handlers

The active behavior is selected by configuration, not by compiling a different binary. The six product personas are configuration profiles:

• gateway
• sidecar
• proxy-server
• proxy-client
• balancer
• bff

These profiles can be represented in light-portal as product-specific config sets. At runtime, light-gateway only sees the resolved files returned by config-server. The binary should not need to know whether the files came from a portal product template, an environment override, or a local fallback.

This keeps deployment simple:

• one binary
• one container image
• one light-pingora framework
• different behavior by remote config

The tradeoff is that config validation must be strong. A product config should not silently start in a different mode if a static root, virtual host, upstream, or chain is wrong.

High-Level Flow

The Pingora gateway request flow should be:

request
  -> match handler.yml paths by path and method
  -> fall back to handler.yml defaultHandlers when no path matches
  -> run request handlers
  -> proxy fixed upstream, route by service_id/service_url, serve static file,
     or return error
  -> run response handlers
  -> response

For static handlers such as virtual-host or path-resource, request_filter writes the response and returns Ok(true) so Pingora does not proxy the request.

For proxy or router handlers, request_filter stores the selected upstream decision in the per-request context and returns Ok(false). upstream_peer and upstream_request_filter then use that context to connect to the right upstream and set headers.

Crate Layout

Keep the first implementation inside frameworks/light-pingora.

Suggested modules:

frameworks/light-pingora/src/
  lib.rs
  handler.rs
  correlation.rs
  cors.rs
  metrics.rs
  proxy.rs
  resource.rs
  router.rs
  service.rs
  token.rs

Responsibilities:

• parse and validate handler.yml
• parse handler.yaml as a compatibility fallback
• parse and validate proxy.yml, router.yml, path-resource.yml, and virtual-host.yml
• build explicit handler registry
• resolve handler chains
• match handler paths and fallback handlers
• capture Java-style {name} path-template variables
• load active handler-specific config files
• serve static SPA content
• select fixed proxy upstreams from proxy.yml
• select dynamic sidecar/router upstreams from router.yml
• resolve sidecar service_id values from pathPrefixService.yml
• retrieve and cache OAuth client-credentials tokens from client.yml
• expose module-registry entries for active handler and traffic/resource config

This keeps the first implementation close to the Pingora lifecycle and avoids premature abstractions for Axum.

If Axum later needs the same handler semantics, extract the framework-neutral parts after the Pingora implementation has stabilized.

Configuration Split

Use handler.yml for the Java-compatible handler middleware contract: handler declarations, reusable chains, path-to-chain mappings, and fallback handlers.

Use Java-compatible product-specific config files for traffic and static resource behavior:

• proxy.yml: fixed inbound reverse proxy targets for gateway, proxy server, balancer, and simple BFF API forwarding.
• router.yml: dynamic outbound routing by service_id or service_url, mainly for sidecar-style deployments.
• path-resource.yml or path-resource.yaml: a single static resource mount.
• virtual-host.yml or virtual-host.yaml: host-based static resource mounts for BFF/SPA deployments.

The product profile selected in light-portal decides which of these files are included and which handlers are active in handler.yml. The Rust binary should not require a separate gateway.yml to duplicate these existing contracts.

Handler-specific files such as correlation.yml, cors.yml, metrics.yml, header.yml, security.yml, apikey.yml, basic-auth.yml, unified-security.yml, and limit.yml stay separate. They are loaded only when the corresponding handler is active in the resolved path/default execution model. Phase 3 implements this active loading for correlation.yml, cors.yml, and metrics.yml. Phase 4 extends the same active-loading and reload model to header.yml, security.yml, apikey.yml, basic-auth.yml, unified-security.yml, and limit.yml.

Remote Config Source

light-gateway starts with enough local bootstrap configuration to contact config-server. The existing Light Fabric runtime then resolves local and remote configuration before light-pingora builds the runtime handler/resource/proxy model.

Startup flow:

1. load local bootstrap files from the configured config directory
2. contact config-server using the configured service identity, environment, and authorization
3. download remote product configuration managed by light-portal
4. merge remote config with local fallback config
5. load handler.yml, applicable traffic/resource config files, and active handler-specific config files
6. validate the complete route and handler model
7. bind Pingora listeners
8. register the runtime instance with the controller

The remote product config should include:

• handler.yml
• proxy.yml for fixed inbound proxy profiles
• router.yml for sidecar/router profiles
• path-resource.yml or virtual-host.yml for static/BFF profiles
• active handler config files
• TLS, trust, or client files required by the runtime
• optional product-specific static file references or mount paths

handler.yml decides which linked handlers are active. A handler that is registered in the binary but not referenced by any configured paths entry or defaultHandlers chain should not be instantiated, should not load its config file, and should never run.

Handler Config

Example handler.yml:

enabled: ${handler.enabled:true}
reportHandlerDuration: ${handler.reportHandlerDuration:false}
handlerMetricsLogLevel: ${handler.handlerMetricsLogLevel:DEBUG}
basePath: ${handler.basePath:/}
handlers: ${handler.handlers:[]}
chains: ${handler.chains:{}}
paths: ${handler.paths:[]}
defaultHandlers: ${handler.defaultHandlers:[]}

The config-server values managed by light-portal provide the concrete arrays and maps:

handler.handlers:
  - correlation
  - headers
  - metrics
  - cors
  - jwt
  - rate-limit

handler.chains:
  spa:
    exec:
      - correlation
      - headers
      - metrics
      - cors
  api:
    exec:
      - correlation
      - headers
      - metrics
      - cors
      - jwt
      - rate-limit
  public:
    exec:
      - correlation
      - headers
      - metrics

handler.paths:
  - path: /api/
    method: GET
    exec:
      - api

handler.defaultHandlers:
  - public

This keeps the same top-level handler.yml contract as the Java framework: enabled, reportHandlerDuration, handlerMetricsLogLevel, basePath, handlers, chains, paths, and defaultHandlers.

The Rust implementation also accepts the Java extension fields additionalHandlers, additionalChains, and additionalPaths. They are merged into the effective handler model before validation.

Unlike Java, the Rust handlers list uses stable short handler IDs. It does not use fully qualified class names, and it does not need @alias because the IDs are already short and stable.

handler.yml is the preferred Rust file name. handler.yaml is accepted as a compatibility fallback because some Java modules and templates use that suffix.

Fixed Proxy Config

proxy.yml should keep the Java inbound reverse-proxy contract. It is used when the deployment has a known set of target upstream URIs.

enabled: ${proxy.enabled:true}
http2Enabled: ${proxy.http2Enabled:false}
hosts: ${proxy.hosts:http://localhost:8080}
connectionsPerThread: ${proxy.connectionsPerThread:20}
maxRequestTime: ${proxy.maxRequestTime:1000}
rewriteHostHeader: ${proxy.rewriteHostHeader:true}
reuseXForwarded: ${proxy.reuseXForwarded:false}
maxConnectionRetries: ${proxy.maxConnectionRetries:3}
maxQueueSize: ${proxy.maxQueueSize:0}
forwardJwtClaims: ${proxy.forwardJwtClaims:false}
metricsInjection: ${proxy.metricsInjection:false}
metricsName: ${proxy.metricsName:proxy-response}

The Rust implementation should parse proxy.hosts as one or more comma separated http:// or https:// targets and select a target with round-robin load balancing. It should preserve rewriteHostHeader, reuseXForwarded, request timeout, retry, and queue settings where Pingora exposes equivalent behavior.

Router Config

router.yml should keep the Java outbound router contract. This is primarily for the sidecar pattern, where earlier handlers resolve service_id, service_url, tokens, and discovery context before the router connects to the downstream service.

http2Enabled: ${router.http2Enabled:true}
httpsEnabled: ${router.httpsEnabled:true}
maxRequestTime: ${router.maxRequestTime:1000}
pathPrefixMaxRequestTime: ${router.pathPrefixMaxRequestTime:{}}
connectionsPerThread: ${router.connectionsPerThread:10}
softMaxConnectionsPerThread: ${router.softMaxConnectionsPerThread:5}
maxQueueSize: ${router.maxQueueSize:0}
rewriteHostHeader: ${router.rewriteHostHeader:true}
reuseXForwarded: ${router.reuseXForwarded:false}
maxConnectionRetries: ${router.maxConnectionRetries:3}
preResolveFQDN2IP: ${router.preResolveFQDN2IP:false}
hostWhitelist: ${router.hostWhitelist:[]}
serviceIdQueryParameter: ${router.serviceIdQueryParameter:false}
urlRewriteRules: ${router.urlRewriteRules:[]}
methodRewriteRules: ${router.methodRewriteRules:[]}
queryParamRewriteRules: ${router.queryParamRewriteRules:{}}
headerRewriteRules: ${router.headerRewriteRules:{}}
metricsInjection: ${router.metricsInjection:false}
metricsName: ${router.metricsName:router-response}

The Java router chooses the target from service_url first, guarded by hostWhitelist, or from service_id plus optional env_tag through service discovery.

Phase 5 implements the Pingora router execution path and keeps the Java configuration shape. The active router handler loads and registers router.yml, selects direct service_url targets after hostWhitelist validation, supports serviceIdQueryParameter, and removes router selection headers before forwarding upstream. It also applies Java-style URL, method, query-parameter, and header rewrite rules.

Rust adds serviceTargets as an interim improvement for service_id routing:

serviceTargets:
  com.networknt.petstore-1.0.0:
    - http://localhost:8080
  com.networknt.petstore-1.0.0|dev:
    - https://petstore-dev.example.com

This lets sidecar-style router flows run in local/static deployments and acts as the fallback when controller discovery is unavailable.

Phase 6 adds the sidecar path-prefix and token flow. Phase 7 adds controller-backed service_id discovery while keeping the same request contract and the same static fallback.

Sidecar Path Prefix And Token Config

pathPrefixService.yml maps request path prefixes to downstream service IDs. The handler writes service_id only when the request does not already provide one.

enabled: ${pathPrefixService.enabled:true}
mapping: ${pathPrefixService.mapping:{}}

Rust intentionally selects the longest path-boundary prefix. This avoids map iteration ambiguity when prefixes overlap and prevents /v1/address from matching /v1/address2.

token.yml gates when the token handler should run:

enabled: ${token.enabled:false}
appliedPathPrefixes: ${token.appliedPathPrefixes:}

The token handler reads the Java-compatible client credentials section from client.yml:

tls:
  verifyHostname: ${client.verifyHostname:true}
oauth:
  multipleAuthServers: ${client.multipleAuthServers:false}
  token:
    cache:
      capacity: ${client.tokenCacheCapacity:200}
    tokenRenewBeforeExpired: ${client.tokenRenewBeforeExpired:60000}
    server_url: ${client.tokenServerUrl:}
    serviceId: ${client.tokenServiceId:com.networknt.oauth2-token-1.0.0}
    proxyHost: ${client.tokenProxyHost:}
    proxyPort: ${client.tokenProxyPort:}
    enableHttp2: ${client.tokenEnableHttp2:true}
    client_credentials:
      uri: ${client.tokenCcUri:/oauth2/token}
      client_id: ${client.tokenCcClientId:}
      client_secret: ${client.tokenCcClientSecret:}
      scope: ${client.tokenCcScope:}
      serviceIdAuthServers: ${client.tokenCcServiceIdAuthServers:}
pathPrefixServices: ${client.pathPrefixServices:}
request:
  connectTimeout: ${client.connectTimeout:2000}
  timeout: ${client.timeout:3000}
  enableHttp2: ${client.enableHttp2:true}

In single-auth-server mode, the handler uses the configured token server and client credentials for all matched paths. In multipleAuthServers mode, it uses service_id or pathPrefixServices to select client_credentials.serviceIdAuthServers[service_id].

The token request follows the Java request shape:

• POST to server_url + uri
• Content-Type: application/x-www-form-urlencoded
• Accept: application/json
• HTTP Basic authentication with client_id:client_secret
• form fields grant_type=client_credentials and optional space-joined scope

The injected header follows the Java gateway rule:

• if the inbound request has no Authorization, inject Authorization: Bearer <token>
• if the inbound request already has Authorization, inject X-Scope-Token: Bearer <token>

The Rust cache is local to the gateway process and is registered as light-pingora/token-cache when a runtime cache registry is available. Cache summaries expose key and expiry metadata but never expose bearer token values. Tokens are refreshed synchronously inside the configured renew-before-expiry window. Async background renewal can be added later if blocking refresh latency becomes visible.

When server_url is not configured, phase 7 discovers the token service from serviceId through the runtime portal-registry client. This requires server.enableRegistry and a live controller registration. A disconnected registry client returns a clear configuration/runtime error instead of silently falling back to an unknown token endpoint.

Static Resource Config

For a single static site, keep path-resource.yml:

path: ${path-resource.path:/public}
base: ${path-resource.base:/opt/light-4j/public}
prefix: ${path-resource.prefix:true}
transferMinSize: ${path-resource.transferMinSize:1024}
directoryListingEnabled: ${path-resource.directoryListingEnabled:false}

For host-based BFF/static sites, keep virtual-host.yml:

hosts: ${virtual-host.hosts:[]}

Example config-server values:

virtual-host.hosts:
  - domain: local.localhost
    path: /
    base: /lightapi/dist
    transferMinSize: 10245760
    directoryListingEnabled: false
  - domain: signin.localhost
    path: /
    base: /signin/dist
    transferMinSize: 10245760
    directoryListingEnabled: false

Rust should preserve the Java domain, path, base, transferMinSize, and directoryListingEnabled fields. It should also add the Rust improvement for SPA fallback: when a static virtual host cannot find a requested browser route and the path does not look like an asset, it should serve index.html from the matched static root.

BFF Wiring Example

The Java BFF config in portal-config-loc/all-in-lt/light-gateway uses handler.paths to send API routes through the default chain, which includes path-prefix service resolution, token handling, and the router. It then uses:

handler.defaultHandlers:
  - cors
  - virtual

That means unmatched browser routes fall through to CORS plus virtual-host static serving. Rust should keep this pattern: handler.yml decides whether a request goes to proxy/router/static handling, based on paths and fallback handlers.

Other product personas use different config file combinations. A BFF commonly uses handler.yml, router.yml, path-prefix/token configs, and virtual-host.yml. A simple proxy or balancer can use handler.yml and proxy.yml. A sidecar uses handler.yml, router.yml, token/cache config, registry/discovery config, and usually no static resource config.

Phase 3 Handler Config

Phase 3 implements the first three Java-compatible cross-cutting handlers.

correlation.yml:

enabled: ${correlation.enabled:true}
autogenCorrelationID: ${correlation.autogenCorrelationID:true}
correlationMdcField: ${correlation.correlationMdcField:cId}
traceabilityMdcField: ${correlation.traceabilityMdcField:tId}

The Rust handler reads X-Correlation-Id and X-Traceability-Id, generates a Java-compatible URL-safe UUID value when correlation is missing, passes the correlation ID to the upstream request, and echoes X-Traceability-Id on the response. It stores the values in the Pingora request context instead of MDC.

cors.yml:

enabled: ${cors.enabled:true}
allowedOrigins: ${cors.allowedOrigins:}
allowedMethods: ${cors.allowedMethods:}
pathPrefixAllowed: ${cors.pathPrefixAllowed:}

The Rust handler accepts the same list/string forms as Java, supports pathPrefixAllowed, short-circuits preflight OPTIONS, rejects disallowed origins with 403, and adds the CORS response headers before static or proxied responses are sent. Rust intentionally uses longest-prefix selection for pathPrefixAllowed so overlapping prefixes are deterministic.

metrics.yml:

enabled: ${metrics.enabled:true}
enableJVMMonitor: ${metrics.enableJVMMonitor:false}
serverProtocol: ${metrics.serverProtocol:http}
serverHost: ${metrics.serverHost:localhost}
serverPath: ${metrics.serverPath:/apm/metricFeed}
serverPort: ${metrics.serverPort:8086}
serverName: ${metrics.serverName:metrics}
serverUser: ${metrics.serverUser:admin}
serverPass: ${metrics.serverPass:admin}
reportInMinutes: ${metrics.reportInMinutes:1}
productName: ${metrics.productName:http-sidecar}
sendScopeClientId: ${metrics.sendScopeClientId:false}
sendCallerId: ${metrics.sendCallerId:false}
sendIssuer: ${metrics.sendIssuer:false}
issuerRegex: ${metrics.issuerRegex:}

Phase 3 parses and registers this config with serverPass masked, records request counts and status classes in memory, and logs request metrics with the matched endpoint and correlation ID. enableJVMMonitor is parsed for config compatibility but is not applicable to Rust. External Influx/APM reporters are deferred until the metrics sink decision is made.

Phase 4 Handler Config

Phase 4 implements the security-oriented Java-compatible handlers that fit the Pingora request metadata model.

header.yml:

enabled: ${header.enabled:false}
request:
  remove: ${header.request.remove:}
  update: ${header.request.update:}
response:
  remove: ${header.response.remove:}
  update: ${header.response.update:}
pathPrefixHeader: ${header.pathPrefixHeader:}

The Rust handler applies request header remove/update rules before proxying and response header remove/update rules before static or proxied responses are sent. Rust intentionally uses longest-prefix selection for pathPrefixHeader so overlapping prefixes are deterministic.

apikey.yml:

enabled: ${apikey.enabled:true}
hashEnabled: ${apikey.hashEnabled:false}
pathPrefixAuths: ${apikey.pathPrefixAuths:[]}

The Rust handler follows the Java rule that no matching path prefix means the handler passes the request. A matching rule validates the configured header against either a plain API key or the Java iterations:saltHex:hashHex PBKDF2-HMAC-SHA1 hash format.

basic-auth.yml:

enabled: ${basic.enabled:false}
enableAD: ${basic.enableAD:true}
allowAnonymous: ${basic.allowAnonymous:false}
allowBearerToken: ${basic.allowBearerToken:false}
users: ${basic.users:[]}

The Rust handler supports configured local users, anonymous path users, and the Java-compatible bearer pass-through mode. LDAP/AD authentication is parsed for configuration compatibility but is not implemented in phase 4.

security.yml:

enableVerifyJwt: ${security.enableVerifyJwt:true}
ignoreJwtExpiry: ${security.ignoreJwtExpiry:false}
enableH2c: ${security.enableH2c:false}
enableMockJwt: ${security.enableMockJwt:false}
jwt:
  certificate: ${security.jwt.certificate:{}}
  clockSkewInSeconds: ${security.jwt.clockSkewInSeconds:60}
  keyResolver: ${security.jwt.keyResolver:}
skipPathPrefixes: ${security.skipPathPrefixes:[]}
passThroughClaims: ${security.passThroughClaims:{}}

The Rust handler verifies Bearer JWTs with configured PEM certificates, honors kid when present, supports RSA and EC algorithms handled by the Rust JWT library, applies clock skew and optional expiry bypass, caches decoded claims, and forwards configured pass-through claims as request headers. Dynamic JWK key service bootstrap and SWT/SJWT verification are deferred until the runtime has the discovery and key-service client surface needed by those flows.

unified-security.yml:

enabled: ${unified-security.enabled:true}
anonymousPrefixes: ${unified-security.anonymousPrefixes:[]}
pathPrefixAuths: ${unified-security.pathPrefixAuths:[]}

The Rust handler supports Java-style path-prefix selection across Basic, JWT, and API-key authentication. Anonymous prefixes bypass authentication. SWT/SJWT rules return a clear not-implemented response until the discovery-backed key flow is added.

limit.yml:

enabled: ${limit.enabled:false}
concurrentRequest: ${limit.concurrentRequest:0}
queueSize: ${limit.queueSize:0}
errorCode: ${limit.errorCode:429}
rateLimit: ${limit.rateLimit:}
headersAlwaysSet: ${limit.headersAlwaysSet:false}
key: ${limit.key:server}
server: ${limit.server:{}}
address: ${limit.address:{}}
client: ${limit.client:{}}
user: ${limit.user:{}}

The Rust handler implements in-memory request rate limiting by server, client address, JWT client ID, or JWT user ID. It emits X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset, and Retry-After when a request is rejected, and it can always emit the rate-limit headers when headersAlwaysSet is enabled. Cluster-wide distributed counters are deferred until there is a concrete gateway clustering requirement.

Handler Registry

Use explicit registration.

#![allow(unused)]
fn main() {
let handlers = PingoraHandlerRegistry::new()
    .register(correlation::descriptor())
    .register(headers::descriptor())
    .register(metrics::descriptor())
    .register(cors::descriptor())
    .register(jwt::descriptor())
    .register(rate_limit::descriptor());
}

No inventory is needed for the first version. Explicit registration is deterministic, testable, and makes the compiled-in handler set clear from the service binary.

The light-gateway binary can register every built-in handler it supports. Registration only makes a handler available. Activation is controlled by handler.yml.

Build the active handler set lazily:

1. parse handler.yml
2. resolve paths and defaultHandlers
3. expand any referenced chains
4. compute the set of referenced handler IDs
5. instantiate only referenced handlers
6. load config only for referenced handlers

This allows one binary to support gateway, sidecar, proxy, balancer, and BFF profiles without requiring unused handler config files.

The registry maps stable config IDs to factories:

#![allow(unused)]
fn main() {
pub struct PingoraHandlerDescriptor {
    pub id: &'static str,
    pub kind: PingoraHandlerKind,
    pub factory: PingoraHandlerFactory,
}
}

Suggested first handler IDs:

• correlation
• headers
• metrics
• cors
• jwt
• api-key
• basic-auth
• rate-limit
• request-size-limit

Trace headers should be handled by correlation; there should not be a separate traceability handler.

Handler API

Use Pingora phases directly. Avoid a generic exchange abstraction until another framework needs it.

The current implementation keeps PingoraHandler as a descriptor/factory surface and executes the built-in phase 3 handlers from light-gateway's Pingora lifecycle. This keeps the first implementation straightforward:

• request_filter resolves the configured chain and runs request-stage handlers in order.
• A request-stage handler can continue, short-circuit with a local response, or select a terminal action such as proxy/static/health.
• upstream_request_filter applies upstream request mutations such as generated correlation IDs.
• response_filter applies response-stage headers and records proxied response metrics.
• Static responses call the same response decoration and metrics code before writing the local response.

Once security/rate-limit handlers are added, this can be lifted into a richer trait with request/upstream/response hooks if the duplication becomes real. It is intentionally not generalized before the Pingora behavior stabilizes.

Response handlers should run before both static and proxied responses are sent. For proxied responses, this maps to Pingora response_filter. For static responses, the static-file renderer calls the same response handler chain before writing the local response.

Request Context

The per-request context should carry route decisions across Pingora phases.

#![allow(unused)]
fn main() {
pub struct GatewayRequestContext {
    pub upstream: Option<ProxyTarget>,
    pub endpoint: String,
    pub method: String,
    pub path_params: BTreeMap<String, String>,
    pub correlation: CorrelationState,
    pub cors: Option<CorsResponseHeaders>,
    pub metrics_enabled: bool,
}
}

The context is created by ProxyHttp::new_ctx() and populated in request_filter.

upstream_peer should only select an upstream after a proxy or router handler has selected one. If no upstream is selected for a proxied request, the implementation should return a clear configuration error rather than silently falling back.

Virtual Hosts

Virtual-host static serving should use the HTTP Host header.

Host normalization rules:

• lowercase the host
• strip the port when present
• reject empty or invalid hosts unless a default virtual host is configured
• exact host match first
• wildcard match such as *.example.com after exact hosts, with the longest matching suffix winning

HTTP host routing is enough for the first implementation.

TLS certificate selection by SNI is separate. The current light-pingora transport uses one Rustls TLS setting for the listener, so the first production options are:

• terminate TLS at ingress or a load balancer
• use a wildcard certificate
• use one certificate with all required SANs

Phase 8 evaluated dynamic multi-cert SNI selection. The current light-pingora build uses Pingora's Rustls listener, and Pingora 0.8 Rustls TLS settings do not support certificate callbacks. For now the production options remain terminating TLS before light-gateway, using a wildcard certificate, or using one certificate with all required SANs. Native multi-cert SNI can be added only after moving to a Pingora TLS backend/version that supports server certificate callbacks or certificate resolution through Rustls.

Static SPA Rendering

Static SPA rendering should be part of the Pingora resource engine, not a generic middleware handler. It is enabled by path-resource.yml or virtual-host.yml, typically for BFF profiles.

Rules for the first implementation:

• support GET and HEAD
• return 405 for unsupported methods on static routes
• canonicalize requested paths under the configured static root
• reject path traversal
• do not serve files outside the static root
• deny dotfiles by default
• do not list directories
• serve index.html for the root path
• support SPA fallback to index.html for non-asset routes
• infer Content-Type from file extension
• set Cache-Control: no-cache for index.html
• set long immutable cache headers for hashed assets
• allow static route prefixes to be bypassed by API routes such as /api/, /oauth/, /mcp/, or /ws/

Recommended cache behavior:

index.html                 Cache-Control: no-cache
*.js, *.css with hash       Cache-Control: public, max-age=31536000, immutable
images/fonts with hash      Cache-Control: public, max-age=31536000, immutable
other assets                Cache-Control: public, max-age=3600

Phase 8 keeps small static files on the simple read-then-write path and streams files whose size is greater than or equal to the configured transferMinSize. Static responses include ETag and Last-Modified, honor If-None-Match and If-Modified-Since, and return 304 without a response body when the browser cache is current.

Proxy And Router Behavior

proxy.yml selects from configured upstream URIs. This is the simpler inbound reverse-proxy case and should be implemented before dynamic sidecar routing.

Fixed proxy target behavior:

• parse comma-separated proxy.hosts
• support http:// and https://
• duplicate a single host internally if retry/load-balancer behavior needs at least two entries
• select upstream with round-robin
• apply timeout, retry, queue, and host-forwarding settings where Pingora supports them

router.yml selects from request metadata. Phase 5 implements direct service_url targets, static serviceTargets for service_id, host whitelist enforcement, and rewrite behavior. Phase 7 adds controller-backed service_id lookup through the runtime portal-registry client and keeps static serviceTargets as a local fallback.

Router target behavior:

• prefer service_url when present and allowed by router.hostWhitelist
• otherwise use service_id plus optional env_tag
• optionally allow service_id from the query string when serviceIdQueryParameter is true
• resolve service_id from controller discovery when the portal-registry client is connected
• fall back to router.serviceTargets for local/static deployments or controller lookup failures
• support URL, method, query-parameter, and header rewrite rules
• remove service_url and service_id headers before forwarding

upstream_peer creates the HttpPeer from the selected upstream:

• address
• TLS enabled
• SNI
• optional host header

upstream_request_filter should set or override upstream headers such as:

• Host
• X-Forwarded-For
• X-Forwarded-Proto
• X-Forwarded-Host
• X-Light-Gateway or equivalent runtime marker

Handler-specific upstream mutations should also run from this phase.

Chain Resolution

Startup should validate handler and selected traffic/resource configuration before binding listeners.

Validation rules:

• every handler ID in handler.yml must exist in the explicit registry
• every chain item must resolve to a registered handler or another chain
• recursive chain references are invalid
• every handler.paths entry must reference existing chains or handlers
• every handler.defaultHandlers entry must reference existing chains or handlers
• proxy.yml hosts must be valid http:// or https:// URIs when the proxy handler is active
• router.yml rewrite rules must be parseable when the router handler is active
• every static virtual host must have a static root
• static roots must be absolute or resolved relative to a configured base
• duplicate exact virtual hosts are invalid
• duplicate handler IDs in the registry are invalid

The resolved model should be immutable and cheap to read:

#![allow(unused)]
fn main() {
pub struct GatewayRuntimeModel {
    pub virtual_hosts: BTreeMap<String, Arc<VirtualHost>>,
    pub default_host: Option<Arc<VirtualHost>>,
    pub chains: BTreeMap<String, Arc<ResolvedHandlerChain>>,
    pub proxy_targets: Vec<Arc<ProxyTarget>>,
}
}

Config reload should continue to swap loaded models atomically. In-flight requests should keep using the handler/resource/proxy/router model they already selected.

Runtime Integration

light-runtime remains responsible for bootstrap, config loading, lifecycle, controller registration, and module registry. light-pingora should load its Pingora-specific handler, traffic, and resource config through the existing runtime config loader.

Module IDs:

• light-pingora/handler
• light-pingora/proxy
• light-pingora/router
• light-pingora/path-prefix-service
• light-pingora/token
• light-client/client
• light-pingora/path-resource
• light-pingora/virtual-host
• light-pingora/correlation
• light-pingora/cors
• light-pingora/metrics
• light-pingora/header
• light-pingora/security
• light-pingora/apikey
• light-pingora/basic-auth
• light-pingora/unified-security
• light-pingora/limit

The module registry should expose:

• handler config snapshot, masked
• proxy, router, path-resource, and virtual-host config snapshots, masked
• active handler IDs
• active chains
• active virtual hosts
• active proxy/router/static capabilities
• reloadable status

The implemented phases use the existing ReloadableModule pattern for active handler, proxy, router, resource, virtual-host, path-prefix service, token, and handler-specific config files. Phase 7 exposes a capabilities summary from get_service_info, including active modules, traffic capabilities, active handlers, chain names, path mappings, default handlers, virtual hosts, and path-resource config.

Suitable First Handlers

Start with handlers that map cleanly to Pingora request and response metadata:

• correlation ID and trace headers
• response headers
• metrics
• CORS
• JWT verification
• API key verification
• basic auth
• request size limit from headers
• simple rate limiting by principal, IP, host, or route

Defer handlers that require deeper body handling:

• request decompression
• response compression policy beyond Pingora modules
• request body sanitizer
• generic body parser
• WebSocket message handlers

Error Model

Handlers and proxy/resource selection should return structured errors that render consistently.

#![allow(unused)]
fn main() {
pub struct HandlerError {
    pub status: u16,
    pub code: Cow<'static, str>,
    pub message: Cow<'static, str>,
    pub metadata: serde_json::Value,
}
}

Security handlers should avoid returning sensitive validation details to the browser. Detailed diagnostics should go to logs with correlation IDs.

Common gateway errors:

• unknown host: 404
• no matching handler path or static resource: 404
• unsupported method for static route: 405
• static file outside root: 403
• missing upstream: startup validation error
• auth failure: 401 or 403
• rate limit: 429

Testing Strategy

Unit tests in light-pingora:

• build active handler set from referenced paths and defaultHandlers
• ignore registered but unreferenced handlers
• do not require config files for unreferenced handlers
• parse valid handler.yml
• reject unknown handler IDs
• reject recursive chains
• resolve path/default handler chains in order
• parse handler.yaml fallback
• merge additionalHandlers, additionalChains, and additionalPaths
• capture path-template variables
• parse CORS list/string and path-prefix config
• classify metrics status codes
• normalize host names and strip ports
• reject duplicate virtual hosts
• match exact virtual hosts
• parse and validate proxy.yml hosts
• parse and validate router.yml rewrite-rule config
• select router targets from direct service_url
• reject direct router targets that do not match hostWhitelist
• select router targets from controller discovery and static serviceTargets
• apply router URL, method, query-parameter, and header rewrites
• parse pathPrefixService.yml and avoid partial-segment path matches
• parse token.yml and the client credentials subset of client.yml
• support single and multiple auth-server token configuration
• discover token service endpoints from client.yml token serviceId
• mask token cache summaries and never expose bearer token values
• expose gateway capabilities in get_service_info
• prevent static path traversal
• deny dotfiles by default
• serve index.html for /
• serve SPA fallback for non-asset paths
• avoid SPA fallback for /api/ proxy routes
• select cache headers for index.html and hashed assets
• stop handler execution on early response
• run response handlers before static response write

Integration tests:

• same binary starts with BFF profile config
• same binary starts with proxy or balancer profile config
• BFF profile can route API paths through configured handlers and serve SPA fallback through defaultHandlers
• static SPA route returns index.html
• static asset route returns correct content type and cache header
• virtual host A and virtual host B serve different roots
• API route is proxied to the configured proxy.yml upstream
• auth handler blocks protected API routes
• public static route does not require auth unless configured

Rollout Plan

Phase 1: Product config and active handler model (implemented)

• keep a single apps/light-gateway binary
• register all built-in handler descriptors explicitly
• resolve active handler IDs from handler.yml
• instantiate only active handlers
• load config only for active handlers
• document product profiles managed by light-portal

Phase 2: BFF and fixed proxy engine (implemented)

• load and register proxy.yml, path-resource.yml, and virtual-host.yml

• match handler.yml paths and fallback handlers in Java-compatible order

• select fixed proxy upstreams from proxy.yml

• match virtual hosts by Host

• serve single-site and virtual-host static content

• implement safe static path resolution

• serve static files from request_filter

• add Rust SPA fallback improvement

• add content type and cache headers

• add traversal, dotfile, fallback, proxy-host, and virtual-host tests

Phase 3: Handler chain execution (implemented)

• run request and response handlers around static and proxied responses
• implement correlation, CORS, and basic metrics
• parse correlation.yml, cors.yml, and metrics.yml
• pass generated correlation IDs upstream
• apply response headers to both static and proxied responses
• log handler duration when reportHandlerDuration is enabled
• defer generic response headers to a handler-specific follow-up

Phase 4: Security and request/response policy handlers (implemented)

• implement JWT, API key, basic auth, and rate-limit handlers
• implement the generic header handler for request and response mutation
• implement unified-security path-prefix selection for Basic, JWT, and API key
• parse Java-compatible security.yml, apikey.yml, basic-auth.yml, unified-security.yml, header.yml, and limit.yml
• add JWT pass-through claim request header mutation
• add path-level chain selection for public SPA and protected API routes

Phase 5: Sidecar router (implemented)

• load and register router.yml
• implement dynamic target selection by service_url or service_id
• enforce hostWhitelist
• support static serviceTargets for service_id routing until runtime discovery is available
• support router URL, method, query-parameter, and header rewrites
• apply router request mutation in upstream_request_filter
• remove router selection headers before forwarding
• include router config in the active reload model
• add sidecar-focused tests

Phase 6: Sidecar path-prefix and token flow (implemented)

• load and register pathPrefixService.yml
• resolve service_id by longest path-boundary prefix
• load and register token.yml
• load and register the token-related view of client.yml
• support single-auth-server and multipleAuthServers client credentials
• cache tokens locally and expose masked cache summaries through the runtime cache registry
• inject Authorization or X-Scope-Token according to inbound request state
• extend reload coverage to pathPrefixService.yml, token.yml, and token-related client.yml
• add sidecar token/path-prefix tests

Phase 7: Discovery and control plane (implemented)

• expose the runtime portal-registry client to framework transports
• add discovery/lookup support to the portal-registry client
• resolve router service_id targets through controller discovery
• keep static router.serviceTargets as a fallback for local/static profiles
• discover token service endpoints from client.yml token serviceId
• expose active capabilities, hosts, paths, handlers, and chains through get_service_info
• atomically replace resolved handler/resource/proxy models on reload

Phase 8: Advanced transport features (implemented)

• add streaming static-file delivery for files at or above transferMinSize
• add conditional static requests with ETag and Last-Modified
• add wildcard virtual hosts with exact-host precedence
• evaluate multi-cert TLS SNI support and document the Rustls limitation

Phase 2 Decisions

• Static roots can be absolute, matching the Java deployment model, or relative to the runtime config directory for local Rust development.
• SPA fallback applies only to browser routes. Paths that look like assets, such as /app.js or /favicon.ico, return 404 when the file is missing.
• Handler path matching supports exact paths and Java/OpenAPI-style {name} path-template segments.

Open Questions

• Should static content support ETag in the first implementation if portal deployments depend on browser cache validation?

MCP Router

Status

Phases 1, 2, 3, and 4 are implemented in light-pingora and light-gateway. The configurable tokenization client remains deferred until light-tokenization is migrated to portal-service/apps/portal-service and the protocol is selected. Stateful backend MCP session mapping is implemented for the single-process gateway session store and documented below.

Purpose

The Java mcp-router module exposes a configured Model Context Protocol endpoint, /mcp by default, and turns configured gateway targets into MCP tools. AI agents can call initialize, tools/list, and tools/call; the router then forwards the tool call to an HTTP service or another MCP server.

In light-fabric this should be a light-pingora handler that is activated by light-gateway through handler.yml. The same gateway binary can contain the MCP router implementation, but each product decides whether it runs by including the mcp handler and the mcp-router.yml configuration from the config server.

This feature is separate from the existing runtime MCP control plane in light-runtime. Runtime MCP is an internal management surface exposed through the portal registry connection. The MCP router is an HTTP-facing gateway feature and is subject to the normal inbound handler chain.

The transport target is MCP Streamable HTTP as defined by the current MCP transport specification: https://modelcontextprotocol.io/specification/2025-06-18/basic/transports.

Goals

• Keep the Java configuration model recognizable: enabled, path, and tools.
• Allow mcp-router.tools to be injected by the config server the same way handler.handlers, handler.chains, handler.paths, and handler.defaultHandlers are injected.
• Activate the router with the existing mcp handler id in handler.yml.
• Expose one MCP endpoint with Streamable HTTP semantics, so /mcp is the only public MCP path for both POST messages and optional GET streams.
• Support MCP JSON-RPC methods needed by the Java module: initialize, notifications/initialized, tools/list, and tools/call.
• Route tools to direct targetHost endpoints, discovered serviceId targets, and backend MCP servers.
• Reuse existing cross-cutting handlers such as correlation, security, CORS, rate limit, header, metrics, and proxy routing where the chain order allows.
• Register the router configuration with the module registry so it can be inspected and reloaded consistently with other light-fabric modules.

Non-Goals

• Do not use Rust dynamic plugins or inventory for runtime tool registration. The active tools are product configuration, not compile-time discovery.
• Do not merge the public MCP router and the internal runtime MCP control plane into one handler.
• Do not implement a full MCP server framework in the first pass. The gateway only needs the methods used by agents to discover and call configured tools.
• Do not copy Java's legacy HTTP+SSE endpoint split as the target transport. Streamable HTTP is the Rust target; legacy SSE can be considered only as a compatibility mode if an older client requires it.
• Do not hardcode tokenization or masking service URLs. Java currently has a hardcoded tokenization endpoint in this path; the Rust port should make that configurable when masking/tokenization is added.

Java Behavior To Map

The Java module has three main pieces:

• McpConfig loads mcp-router.yml with enabled, path, and tools.
• McpHandler owns the HTTP MCP endpoint and JSON-RPC protocol handling.
• McpToolRegistry stores configured tool implementations by name.

Java configuration:

enabled: ${mcp-router.enabled:true}
path: ${mcp-router.path:/mcp}
maxSessions: ${mcp-router.maxSessions:10000}
maxSessionsPerClient: ${mcp-router.maxSessionsPerClient:100}
tools: ${mcp-router.tools:}

Each tool supports these fields:

- name: weather
  description: Get weather information
  protocol: http
  serviceId: com.networknt.weather-1.0.0
  envTag: dev
  targetHost: http://localhost:7081
  path: /weather
  method: GET
  endpoint: /weather@get
  apiType: http
  inputSchema:
    type: object
    properties:
      city:
        type: string
  toolMetadata: {}

The Java handler currently supports:

• GET /mcp as an SSE compatibility endpoint. It creates a session id and emits an endpoint event pointing to /mcp?sessionId=....
• POST /mcp for JSON-RPC messages.
• initialize, returning protocol version, tool capabilities, and server info.
• notifications/initialized, returning no response.
• tools/list, optionally filtered by params.query or params.intent.
• tools/call, forwarding arguments to the configured tool.

The Java tool execution supports two target types:

• HTTP tools call a configured HTTP endpoint. GET maps arguments to query parameters. Other methods send the arguments as a JSON body.
• MCP proxy tools call a backend MCP server by sending a JSON-RPC tools/call request to the configured backend path.

Java also includes rule-based access checks, response filtering, masking, and tokenization around tool calls. The Rust version now implements access checks, response filtering, and schema-driven request masking without hardcoded service endpoints. Tokenization is intentionally deferred.

The Rust implementation should map this behavior to MCP Streamable HTTP rather than keeping Java's legacy HTTP+SSE transport as the default. Streamable HTTP uses one MCP endpoint path. Clients send JSON-RPC messages with POST /mcp; the server can return either a single application/json response or text/event-stream from that same POST when streaming is needed. Clients may also issue GET /mcp to open an optional server-to-client SSE stream on the same endpoint.

Resolved Decisions

• Use Streamable HTTP so only one public MCP endpoint, normally /mcp, is exposed.
• Defer the tokenization client design until light-tokenization is migrated into portal-service/apps/portal-service and its protocol is selected.
• Reuse the light-4j access-control.yml compatibility contract for MCP, REST, and JSON-RPC authorization.
• Do not add configured per-tool outbound headers. Backend tool calls should pass through the headers received from the agent, subject only to headers that the HTTP client must regenerate for a new outbound request and MCP session headers that the gateway must map or regenerate.

Rust Architecture

Add the MCP router to light-pingora because it is a request/response gateway handler. light-gateway should wire it into the existing handler descriptor table and runtime state.

Proposed modules:

frameworks/light-pingora/src/access_control.rs
frameworks/light-pingora/src/mcp.rs

Primary types:

#![allow(unused)]
fn main() {
pub struct McpRouterConfig {
    pub enabled: bool,
    pub path: String,
    pub tools: Vec<McpToolConfig>,
}

pub struct McpToolConfig {
    pub name: String,
    pub description: String,
    pub protocol: Option<String>,
    pub service_id: Option<String>,
    pub env_tag: Option<String>,
    pub target_host: Option<String>,
    pub path: String,
    pub method: HttpMethod,
    pub endpoint: Option<String>,
    pub api_type: McpToolType,
    pub input_schema: serde_json::Value,
    pub tool_metadata: serde_json::Value,
}

pub struct McpRouterRuntime {
    pub config: ArcSwap<McpRouterConfig>,
    pub client: reqwest::Client,
    pub registry_client: Option<Arc<PortalRegistryClient>>,
}
}

The exact field names should follow the existing light-fabric serde naming style while accepting the Java config names through aliases:

• serviceId
• envTag
• targetHost
• apiType
• inputSchema
• toolMetadata

mcp-router.yml should be the primary Rust file name, but the loader should also accept mcp-router.yaml for Java compatibility.

Tool Registration

The router does not need global static registration. Build an immutable tool map when mcp-router.yml is loaded:

McpRouterConfig -> BTreeMap<String, McpToolConfig> -> Arc<McpRouterState>

On reload, build a new state and atomically swap the Arc. In-flight requests continue with the old state.

This is simpler than Java's static McpToolRegistry and avoids Rust plugin complexity. It also matches the light-fabric product model: all handlers can be linked into one binary, while the config server decides which handlers and tools are active for a product.

Request Flow

The mcp handler should participate in the normal handler chain:

request
  -> correlation
  -> metrics
  -> cors
  -> security or unified security
  -> limit
  -> mcp
  -> proxy or route handler, only if mcp did not consume the request
response
  -> header
  -> metrics
  -> access log

When the request path matches mcp-router.path:

• POST parses a JSON-RPC message. Requests return either application/json for a single response or text/event-stream for a streamed response on the same endpoint. Notifications and JSON-RPC responses sent by the client return 202 Accepted with no body when accepted.
• GET with Accept: text/event-stream may open a server-to-client SSE stream on the same endpoint. If the gateway has no server-initiated messages to stream, it should return 405 Method Not Allowed.
• DELETE should terminate the gateway session and any mapped backend MCP sessions. Until session termination is implemented, it can return 405 Method Not Allowed.
• Other methods return 405 Method Not Allowed.

When the path does not match, the handler continues to the next handler in the configured chain.

The handler must be safe to include in shared chains. If mcp-router.enabled is false, or the mcp handler is not in handler.yml, no MCP route is exposed.

JSON-RPC Handling

Supported methods:

initialize
notifications/initialized
tools/list
tools/call

initialize response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "protocolVersion": "2024-11-05",
    "capabilities": {
      "tools": {
        "listChanged": true
      }
    },
    "serverInfo": {
      "name": "light-gateway-mcp",
      "version": "1.0.0"
    }
  }
}

tools/list returns configured tools with name, description, and inputSchema. It should preserve Java's simple filtering:

• params.query matches tool name or description.
• params.intent matches tool name or description.

tools/call validates params.name, finds the tool, validates or forwards params.arguments, and returns either:

{
  "content": [
    {
      "type": "text",
      "text": "..."
    }
  ]
}

or the structured result returned by the backend MCP server.

JSON-RPC errors should use the same codes as Java where practical:

-32700 parse error
-32601 method or tool not found
-32602 invalid params
-32000 tool execution failed
-32001 access denied

Rust improvement: malformed transport payloads should return a clear HTTP 400 with a JSON-RPC error body instead of a generic HTTP 500.

For Streamable HTTP:

• Clients must send each JSON-RPC message as a separate POST to the MCP endpoint.
• Clients should send Accept: application/json, text/event-stream.
• The router should negotiate and honor MCP-Protocol-Version.
• The router terminates the client-facing MCP session. initialize responses should include a gateway-owned Mcp-Session-Id, and later client requests should be validated against that gateway session.

MCP Session Management

The MCP router should use a facade model. To the agent, light-gateway is the MCP server. To upstream MCP targets, light-gateway is an MCP client. This keeps gateway security, access-control policy, masking, response filtering, and tool aggregation in one place while still respecting upstream MCP session state.

There are two distinct session scopes:

• Frontend session: the session between the MCP client and light-gateway.
• Backend session: one upstream MCP server session owned by the gateway for a specific frontend session and backend target.

The frontend session is created during client initialize:

1. The client sends initialize to mcp-router.path.
2. The gateway returns the MCP capabilities it exposes and a gateway-generated Mcp-Session-Id.
3. The gateway stores session state keyed by that id. The state should include the negotiated protocol version, client info, security principal or relevant auth context, and any backend MCP sessions created for this client session.
4. Later client requests must include the gateway session id. Unknown or expired session ids should fail before tool execution.
5. A client DELETE request, explicit expiry, or gateway shutdown should close all backend sessions associated with the frontend session.

The in-memory gateway store uses a 30-minute idle timeout, a configurable maximum frontend session count, and a configurable per-client frontend session count. Expired sessions are purged lazily during later MCP requests, and any mapped backend MCP sessions are closed during that purge. If the store is still full after lazy purge, or the client already owns the maximum allowed sessions, new initialize requests fail without issuing another session id.

The per-client key is derived from the authenticated principal when available, preferring client_id, then user_id, email, and host. If no security principal is available, the key falls back to MCP clientInfo.name and clientInfo.version from the initialize request.

For a single gateway process, the session store can start in memory. In a multi-pod deployment, the store should be external, such as Redis, or ingress must provide sticky routing for all requests that carry the same Mcp-Session-Id.

Backend handling depends on the tool type.

For apiType: http, the backend is a normal stateless API:

1. No backend MCP session is created.
2. The gateway translates tools/call arguments into a normal HTTP request.
3. GET tools serialize arguments into the query string; body-capable methods send JSON.
4. The gateway wraps the HTTP response into an MCP tools/call result.
5. User-specific auth, tenant, correlation, and trace headers come from the frontend session or inbound request and are applied to the outbound HTTP call as normal gateway headers.

For apiType: mcp, the backend is a stateful MCP server:

1. The gateway lazily initializes the backend session the first time a frontend session calls a tool for that backend target. If future dynamic tool discovery depends on the backend, this initialization can happen before tools/list instead.
2. The gateway sends initialize to the backend MCP endpoint as an MCP client. It should use the client-requested protocol version when supported and pass only the capabilities it needs upstream.
3. If the backend returns Mcp-Session-Id, the gateway stores it in a mapping keyed by the gateway session id and backend target identity.
4. The gateway sends notifications/initialized to the backend when the backend session is established.
5. For later backend calls, the gateway sends the backend session id to that backend. It must not forward the frontend gateway session id as if it were a backend session id.
6. The gateway still performs access checks before calling the backend and response filtering after the backend response.
7. When the frontend session ends, the gateway should terminate each mapped backend MCP session to avoid leaking backend resources.

The backend target identity used in the session map should be stable across requests. It should include the resolved route information that distinguishes one backend MCP endpoint from another, such as targetHost or serviceId, envTag, protocol, and tool path.

When the router aggregates tools from both MCP servers and normal APIs, the client still sees one gateway MCP session and one tools/list response. The gateway registry decides how each tools/call is executed:

The configured tools/list remains the gateway's public contract. A future dynamic-discovery mode may call backend MCP tools/list and merge those tools with configured HTTP tools, but that must still preserve the gateway's policy surface and avoid exposing backend tools that are not authorized for the product.

HTTP Tool Execution

For apiType: http or missing apiType:

1. Resolve the target base URL.
2. Build the target URL from base URL plus tool path.
3. For GET, serialize arguments with url::form_urlencoded.
4. For POST, PUT, and PATCH, send arguments as JSON.
5. Pass through the inbound agent headers to the backend tool call so caller identity, authorization, correlation, tenant, locale, and tracing context are preserved.
6. Let the HTTP client regenerate transport-specific headers for the new outbound request, such as Host, Content-Length, Transfer-Encoding, and connection management headers.
7. Treat 2xx as success.
8. Parse JSON responses as structured MCP results.
9. Wrap non-JSON responses as MCP text content.
10. Return an empty 2xx response as { "result": "success" }.

Target resolution:

• Prefer targetHost for direct calls.
• Otherwise use serviceId, protocol, and envTag through the existing portal registry discovery client.
• If neither is available, return a tool execution error.

MCP Proxy Tool Execution

For apiType: mcp:

1. Resolve the target base URL the same way as HTTP tools.
2. Ensure a backend MCP session exists for the current gateway session and backend target. If none exists, initialize the backend MCP endpoint and store the returned backend Mcp-Session-Id.
3. POST to the configured backend path.
4. Pass through the inbound agent headers to the backend MCP server, with transport-specific headers regenerated for the new outbound request. Replace any frontend gateway Mcp-Session-Id with the mapped backend session id for this backend target.
5. Send a backend JSON-RPC request:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "tool-name",
    "arguments": {}
  }
}

6. If the backend returns error, map it to -32000.
7. If the backend returns result, return it to the caller.
8. On frontend session termination or expiry, close the backend MCP session.

This preserves the Java McpProxyTool behavior while using Rust's typed JSON-RPC models where possible and adds the MCP session mapping required by stateful backend MCP servers.

Configuration Loading

The router should be loaded as a normal light-fabric module:

config-server product values
  -> mcp-router.yml placeholders
  -> light-gateway startup
  -> light-pingora mcp router state

Example product values:

mcp-router.enabled: true
mcp-router.path: /mcp
mcp-router.tools:
  - name: get_pet
    description: Get a pet by id.
    targetHost: http://petstore:8080
    path: /v1/pets
    method: GET
    inputSchema:
      type: object
      properties:
        id:
          type: string

Example handler.yml path wiring:

handlers:
  - correlation
  - metrics
  - cors
  - jwt
  - mcp
  - proxy

chains:
  default:
    - correlation
    - metrics
    - cors
    - jwt
    - proxy
  mcp:
    - correlation
    - metrics
    - cors
    - jwt
    - mcp

paths:
  - path: /mcp
    method: POST
    exec:
      - mcp
  - path: /mcp
    method: GET
    exec:
      - mcp

defaultHandlers:
  - proxy

The exact chain names are product choices. The important point is that /mcp can have a narrow chain while normal API proxy traffic keeps the normal proxy chain.

Module Registry

The MCP router should register its configuration with the module registry:

• module name: mcp-router
• config files: mcp-router.yml, with mcp-router.yaml as compatibility fallback
• enabled status
• configured path
• tool count
• tool names

The module registry should mask any future secret fields in toolMetadata, headers, or credential configuration.

Reload behavior:

1. Reload mcp-router.yml.
2. Validate duplicate tool names, missing paths, unsupported methods, and target resolution fields.
3. Build a new immutable router state.
4. Swap the runtime state atomically.
5. Report the updated module registry status.

Security And Policy

The first layer of protection should be the handler chain. Products can place JWT, API key, basic auth, unified security, CORS, rate limit, and header handlers before or after mcp as needed.

Because MCP Streamable HTTP is browser-reachable, the mcp handler must also validate the Origin header according to the configured CORS or security policy. Invalid origins should fail before tool execution.

Fine-grained tool authorization should be added after the base router:

• Reuse the existing light-4j access-control.yml model as the compatibility contract. access-control.yml controls enabled, accessRuleLogic, defaultDeny, and skipPathPrefixes; rule.yml provides ruleBodies and endpointRules.
• Make the access policy endpoint stable. Java uses the tool endpoint field, such as /weather@get; when omitted, Rust derives {path}@{method}.
• Include correlation id, caller claims, request headers, tool name, endpoint, and arguments in the policy input.
• Support default deny when access control is enabled and no req-acc rule matches.
• Provide built-in Rust actions compatible with the Java class names used by current config: RoleBasedAccessControlAction, ResponseColumnFilterAction, and ResponseRowFilterAction.

Response filtering should be implemented as a second policy stage:

• Apply policy after backend execution and before JSON-RPC response emission.
• Support both structuredContent and single text content responses, matching Java's behavior.
• Match endpoint rules exactly first, then Java-style path templates and parent path entries such as /v1/accounts@get for /v1/accounts/123@get.

Masking and tokenization handling:

• Preserve Java schema extensions: x-mask, x-mask-pattern, and x-tokenize.
• Parse these extensions from inputSchema as serde_json::Value.
• Apply schema-driven x-mask request masking before backend tool execution.
• Keep x-tokenize as a future extension point. Do not call a tokenization service until the portal-service tokenization protocol is finalized.
• Do not hardcode a tokenization service URL. The tokenization client should be designed after light-tokenization is migrated into portal-service/apps/portal-service, whether the final protocol is JSON-RPC, MCP, or gRPC.

Per-tool outbound headers would mean headers that the MCP router adds from tool configuration when it calls a specific backend target, for example a configured Authorization, X-API-Key, tenant routing header, or vendor-specific version header. We do not need that feature. The required behavior is header pass-through: backend tool calls receive the headers that came from the agent, while the HTTP client regenerates only the transport-specific headers required for a valid outbound request. MCP session headers are not normal pass-through headers. The gateway owns the frontend Mcp-Session-Id and maps it to backend session ids when an upstream MCP server is involved.

Relationship To Existing Runtime MCP

light-runtime already has RuntimeMcpHandler for runtime management tools. That should remain internal and registry-facing.

The gateway MCP router should not automatically expose runtime management tools. If a product needs that bridge later, add an explicit configured tool type, for example:

apiType: runtime

That keeps public agent-facing tools separate from management tools and avoids accidentally exposing cache, module, or service operations through a public gateway route.

Phased Implementation

Phase 1: Core Router

• Add mcp-router.yml config parsing in light-pingora.
• Accept tools as either a YAML array or a JSON string to match Java config server injection behavior.
• Add immutable tool map validation.
• Implement the base Streamable HTTP single endpoint: unary POST /mcp, Accept validation for application/json and text/event-stream, 202 Accepted for accepted notifications, and 405 for unsupported methods.
• Implement JSON-RPC initialize, notifications/initialized, tools/list, and tools/call.
• Implement direct targetHost HTTP tools.
• Pass through agent request headers to direct HTTP and backend MCP tool calls, except MCP session headers that the gateway must map separately.
• Wire the existing mcp handler id in light-gateway.
• Register module status and config with the module registry.
• Add parser and handler tests.

Status: implemented.

Phase 2: Discovery And MCP Proxy

• Resolve serviceId, protocol, and envTag through the existing portal registry discovery client.
• Implement apiType: mcp backend proxy tools.
• Add reload support with atomic state swap.
• Add tests with fake discovery and backend MCP responses.

Status: implemented.

Phase 3: Streamable HTTP Streaming

• Add streamed text/event-stream responses from POST /mcp for long-running tool calls or server-to-client messages related to the originating request.
• Add optional GET /mcp server-to-client streams on the same endpoint.
• Track frontend sessions when Mcp-Session-Id is issued. Return 405 for standalone GET streams until server-initiated messages are implemented.
• Add tests for content negotiation, 202 Accepted notifications, streamed POST responses, and optional GET behavior.

Status: implemented.

Phase 4: Policy, Filtering, Masking

• Add tool-level authorization using the access-control.yml compatibility contract.
• Add response filtering for structured and text MCP results.
• Add schema-driven request masking.
• Add MCP tool-call log fields for tool name, endpoint, duration, status, and policy outcome.

Status: implemented for access control, response filtering, and request masking. Tokenization is deferred until the portal-service tokenization client is designed.

Phase 5: Stateful MCP Backend Sessions

• Add a gateway session store keyed by frontend Mcp-Session-Id.
• Validate later client requests against the gateway session.
• For apiType: mcp, maintain backend session mappings keyed by gateway session id and backend target identity.
• Lazily initialize backend MCP sessions by sending backend initialize, capturing backend Mcp-Session-Id, and sending notifications/initialized.
• Replace the frontend session id with the mapped backend session id on upstream MCP calls.
• Terminate mapped backend MCP sessions when the frontend session is deleted, expires, or the gateway shuts down.
• Add tests for frontend session validation, backend session creation, backend session reuse, and backend session termination.

Status: implemented for the in-memory frontend session store, configurable global and per-client session caps, 30-minute lazy idle expiry, lazy backend initialization, backend Mcp-Session-Id mapping, backend session reuse, and explicit DELETE teardown. Shutdown cleanup, external session storage, and multi-backend isolation tests remain future hardening for multi-pod deployments.

Testing Strategy

• Config tests:
  • empty config
  • disabled config
  • duplicate tool names
  • tools as YAML array
  • tools as JSON string
  • inputSchema as object and string
• JSON-RPC tests:
  • initialize
  • notifications/initialized
  • notification returns 202 Accepted
  • tools/list
  • tools/list with query and intent
  • missing method
  • invalid params
  • malformed JSON
• Streamable HTTP tests:
  • single /mcp endpoint handles POST
  • POST validates Accept
  • unsupported methods return 405
  • optional GET stream returns 405 until enabled
• Tool execution tests:
  • direct GET with encoded arguments
  • direct POST with JSON arguments
  • non-JSON backend response
  • empty 2xx backend response
  • non-2xx backend response
  • agent headers are forwarded to backend tool calls
  • discovered service target
  • backend MCP proxy success and error
• Handler chain tests:
  • /mcp consumed by mcp
  • non-MCP path continues to the next handler
  • disabled router does not expose /mcp
• Reload tests:
  • tool added
  • tool removed
  • invalid reload keeps the prior good state

Remaining Decisions

• Confirm whether Phase 1 includes only unary Streamable HTTP POST or also streamed POST responses.
• Decide the tokenization client protocol after light-tokenization is migrated into portal-service/apps/portal-service.
• Map the Java access-control.yml schema to Rust policy execution and define how it will be shared by REST, JSON-RPC, and MCP handlers.

LLM Gateway

Status

Design proposal. The current light-agent runtime selects one active model provider from model-provider.yml. That is acceptable if the selected provider is an LLM gateway endpoint. The agent does not need to know how many upstream providers the gateway can reach.

Purpose

The LLM gateway is a centralized model access layer for agents and services. Instead of each agent carrying credentials, endpoint details, routing rules, and provider fallback logic, each agent calls one gateway endpoint. The gateway then routes the request to OpenAI, Azure OpenAI, Bedrock, Anthropic, Gemini, Ollama, Codex, or another provider based on agent configuration, model policy, prompt characteristics, capability requirements, health, cost, and compliance constraints.

This keeps light-agent simple and matches the current bootstrap model:

1. startup.yml is local.
2. Runtime configuration is fetched from config-server.
3. The agent loads one model provider after bootstrap.
4. That provider can be an OpenAI-compatible LLM gateway.
5. The gateway owns multi-provider fan-out.

Goals

• Keep agents configured with one active model endpoint.
• Support many upstream LLM providers at the gateway at the same time.
• Allow provider routing by agent, service id, environment, prompt intent, requested capability, logical model name, cost, latency, region, and health.
• Keep provider credentials out of agent pods and agent config.
• Preserve the existing model-provider abstraction for direct provider access and reuse it inside the gateway where useful.
• Expose a provider-compatible HTTP API so existing agents can use the gateway without a new SDK.
• Support normal light-fabric bootstrap, config-server overrides, module registry visibility, config reload, controller registration, and audit.
• Make gateway decisions explainable enough for operations and compliance.

Non-Goals

• Do not make light-agent load many providers directly for this use case. Multi-provider routing belongs in the gateway.
• Do not require every agent to understand provider-specific fields such as AWS region, Azure deployment name, or Anthropic max token settings.
• Do not expose upstream provider secrets through tools/list, diagnostics, or agent-visible configuration.
• Do not depend on an LLM classification call for every routing decision. The gateway should support deterministic routing first and optional classifier routing later.
• Do not merge the LLM gateway with the MCP router. The LLM gateway routes model calls; the MCP router routes tool calls.

Relationship To Existing Components

Light-Agent

light-agent should continue to select one model provider after runtime bootstrap. For an LLM gateway deployment, the selected provider is the gateway:

model-provider.provider: compatible
model-provider.model: agent-default
compatible.name: llm-gateway
compatible.baseUrl: https://llm-gateway.light-gateway:8443/v1
compatible.apiKey: ${secret.llmGatewayApiKey}

The model-provider.model value becomes a logical model name. It does not need to be an upstream provider model id. Examples:

model-provider.model: agent-default
model-provider.model: fast
model-provider.model: reasoning
model-provider.model: coding
model-provider.model: pii-safe

The gateway maps the logical model to a physical provider and model.

Light-Gateway

The LLM gateway should be implemented as a light-gateway product capability, activated by handler/config. This keeps LLM egress under the same gateway family that already handles MCP routing, auth, rule execution, metrics, service discovery, bootstrap, and reload.

The first implementation can expose an OpenAI-compatible endpoint:

POST /v1/chat/completions

That is enough for CompatibleProvider and many external clients. Later phases can add:

POST /v1/responses
GET  /v1/models

Model Provider Crate

The gateway can reuse crates/model-provider for upstream calls. The crate already contains concrete providers and meta-providers:

• OpenAI
• Azure OpenAI
• Anthropic
• Bedrock
• Codex
• Compatible
• Gemini
• GLM
• Ollama
• OpenRouter
• Telnyx
• Copilot
• CLI providers where operationally appropriate
• RouterProvider
• ReliableProvider

For the gateway, direct concrete providers are upstream adapters. Routing and fallback should be controlled by gateway config and policy, not by each agent.

Request Flow

agent
  -> LLM provider trait
  -> CompatibleProvider
  -> light-gateway /v1/chat/completions
  -> auth, correlation, policy, rate limit
  -> LLM route decision
  -> upstream provider adapter
  -> upstream LLM provider
  -> normalized response
  -> audit, metrics, token usage
  -> agent

The agent sees one model provider. The gateway sees the full routing context.

Routing Inputs

The gateway should make routing decisions from a combination of trusted inputs:

• Authenticated caller identity from JWT, mTLS, or gateway-authenticated service registration.
• Agent metadata such as host id, agent definition id, service id, environment, tenant, and account.
• Logical model name from the request body.
• Request capabilities: tool calling, vision, JSON mode, long context, reasoning, streaming, prompt caching.
• Prompt features: intent keywords, size, language, sensitivity markers, coding vs support vs workflow execution.
• Configured policy: allowed providers, blocked providers, region constraints, cost tier, data residency, fallback chain.
• Runtime health: provider availability, error rate, latency, quota pressure.

If metadata is supplied as headers, the gateway should only trust those headers from authenticated internal clients. Otherwise it should derive identity from the token or connection.

Suggested internal headers:

X-Light-Request-Id
X-Light-Service-Id
X-Light-Env-Tag
X-Light-Agent-Host-Id
X-Light-Agent-Definition-Id
X-Light-Tenant-Id

Routing Stages

Routing should be deterministic before it is intelligent.

1. Explicit route

   If the request asks for a logical model with a direct configured route, use that route.

2. Agent policy

   Apply policy for the authenticated agent or service. This can narrow the allowed logical models and upstream providers.

3. Capability filter

   Remove upstreams that cannot satisfy required capabilities such as tools, vision, long context, or streaming.

4. Prompt classifier

   Optionally classify the prompt into a routing domain such as fast, reasoning, coding, customer-support, or restricted-data.

5. Cost and latency preference

   Choose the cheapest or fastest provider that satisfies policy and capability constraints.

6. Health and fallback

   If the selected upstream is unhealthy or returns a retryable error, follow a configured fallback chain.

Gateway Configuration

The gateway should use a dedicated config file, for example llm-gateway.yml, loaded through the same runtime config layering as other light-fabric modules.

Example:

enabled: ${llm-gateway.enabled:true}
pathPrefix: ${llm-gateway.pathPrefix:/v1}
defaultRoute: ${llm-gateway.defaultRoute:agent-default}

routes:
  agent-default:
    provider: openai-prod
    model: gpt-4o
    fallbacks:
      - provider: bedrock-us
        model: anthropic.claude-3-5-sonnet-20240620-v1:0

  fast:
    provider: openai-prod
    model: gpt-4o-mini

  reasoning:
    provider: bedrock-us
    model: anthropic.claude-3-7-sonnet-20250219-v1:0
    requiredCapabilities:
      - tools
      - long-context

providers:
  openai-prod:
    type: openai
    baseUrl: ${llm.openai.baseUrl:https://api.openai.com/v1}
    apiKey: ${llm.openai.apiKey:}
    maxTokens: ${llm.openai.maxTokens:}
    costTier: medium
    regions:
      - global

  bedrock-us:
    type: bedrock
    region: ${llm.bedrock.region:us-east-1}
    accessKeyId: ${llm.bedrock.accessKeyId:}
    secretAccessKey: ${llm.bedrock.secretAccessKey:}
    sessionToken: ${llm.bedrock.sessionToken:}
    costTier: high
    regions:
      - us-east-1

agentPolicies:
  com.networknt.agent.account-1.0.0:
    defaultRoute: agent-default
    allowedRoutes:
      - agent-default
      - fast
      - reasoning
    blockedProviders: []
    dataResidency:
      allowedRegions:
        - us-east-1
        - global

fallback:
  maxRetries: ${llm-gateway.fallback.maxRetries:1}
  baseBackoffMs: ${llm-gateway.fallback.baseBackoffMs:100}

The exact schema can evolve, but the important boundary is stable:

• Agent config points to one gateway endpoint.
• Gateway config owns provider inventory and route policy.
• Provider secrets are masked in module registry output.

Provider Inventory

Each configured provider should have:

• A stable provider id.
• A provider type.
• Provider-specific connection settings.
• Supported capabilities.
• Allowed regions.
• Cost tier.
• Timeout and retry settings.
• Optional quota metadata.
• Optional tenant or account restrictions.

Provider ids should be operational names, not user-visible model names:

providers:
  openai-prod:
    type: openai
  openai-eu:
    type: azure-openai
  bedrock-us:
    type: bedrock
  local-ollama:
    type: ollama

Logical model names are route names. They are safe for agents to request.

Request And Response Contract

The first API should be OpenAI-compatible enough for CompatibleProvider:

POST /v1/chat/completions
Authorization: Bearer <agent-or-service-token>
Content-Type: application/json

Request:

{
  "model": "agent-default",
  "messages": [
    {"role": "system", "content": "You are a support agent."},
    {"role": "user", "content": "Help me investigate this account."}
  ],
  "temperature": 0.7,
  "tools": []
}

Response:

{
  "id": "chatcmpl-...",
  "object": "chat.completion",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "..."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 1200,
    "completion_tokens": 240,
    "total_tokens": 1440
  },
  "light_gateway": {
    "route": "agent-default",
    "provider": "openai-prod",
    "model": "gpt-4o"
  }
}

The light_gateway field should be optional and controlled by diagnostics policy. It is useful for internal debugging, but may be hidden from external clients.

Tool Calling

Tool calling remains an agent responsibility, but model-native tool-call generation flows through the LLM gateway.

The LLM gateway should:

• Accept OpenAI-style tool definitions from the agent.
• Convert tool definitions to the upstream provider's native format when possible.
• Normalize provider tool-call responses back to the OpenAI-compatible shape.
• Return clear errors when a route cannot support tool calling.

The gateway should not execute MCP tools. The agent still calls light-gateway MCP endpoints for tools/list and tools/call.

Security

The gateway becomes the model egress control point, so it must enforce:

• Authentication for every model request.
• Authorization for logical models and provider routes.
• Tenant isolation.
• Provider allowlists and denylists.
• Secret masking in module registry and diagnostics.
• Optional request/response redaction or tokenization hooks.
• Data residency rules.
• Rate limits by tenant, agent, route, and provider.
• Audit records for route selection and usage.

Provider credentials should live only in gateway config or the secret system feeding config-server. They should not be copied into agent config.

Observability

Each gateway model call should produce structured telemetry:

• Request id.
• Caller identity.
• Agent id and service id when available.
• Logical model.
• Selected provider and physical model.
• Routing reason.
• Fallback attempts.
• Prompt and completion token counts.
• Latency by stage.
• Provider status code and error class.
• Cache hit or prompt-cache usage where available.
• Policy decisions.

Metrics should support dashboards by route, provider, tenant, and agent.

Config Reload

The gateway should register llm-gateway.yml in the module registry and support runtime reload.

Reload should be atomic:

1. Load and validate the new config.
2. Build provider clients and route tables.
3. Reject invalid route references before swapping state.
4. Swap active routing state.
5. Keep in-flight requests on the old state.

Validation should catch:

• Unknown provider ids.
• Unknown provider types.
• Routes without a provider.
• Fallbacks pointing to missing providers.
• Logical routes that require capabilities no provider can satisfy.
• Missing required provider settings for active routes.

Agent Configuration Pattern

For a direct provider deployment:

model-provider.provider: bedrock
model-provider.model: anthropic.claude-3-5-sonnet-20240620-v1:0
bedrock.region: us-east-1

For a gateway deployment:

model-provider.provider: compatible
model-provider.model: agent-default
compatible.name: llm-gateway
compatible.baseUrl: https://llm-gateway.light-gateway:8443/v1
compatible.apiKey: ${llmGateway.agentApiKey}

The second form is the preferred enterprise model once centralized routing is available.

Phased Implementation

Phase 1: OpenAI-Compatible Gateway Endpoint

• Add llm-gateway.yml.
• Add a light-gateway handler for /v1/chat/completions.
• Support non-streaming OpenAI-compatible requests and responses.
• Route by logical model name to one configured upstream provider.
• Mask provider secrets in module registry.
• Add basic audit and metrics.

Phase 2: Policy, Fallback, And Reload

• Add per-agent route policy.
• Add health-aware fallback chains.
• Support runtime reload with atomic state swap.
• Add diagnostics endpoint or module registry details for active routes.

Phase 3: Capability-Aware Routing

• Add capability metadata for each provider route.
• Route by tools, vision, long context, streaming, and JSON mode.
• Normalize tool-call request and response shapes across providers.

Phase 4: Prompt-Aware Routing

• Add deterministic prompt classifiers.
• Add optional lightweight model or embedding classifier for complex routing.
• Record routing reasons for audit.

Phase 5: Advanced Provider Features

• Add streaming.
• Add /v1/responses.
• Add prompt caching hints.
• Add quota-aware routing.
• Add data redaction or tokenization hooks when the tokenization service contract is finalized.

Open Questions

• Should the first implementation live in light-pingora as a handler module or in a new llm-gateway crate used by light-gateway?
• Should logical model policy be stored only in config-server values, or also managed by portal database tables for runtime UI edits?
• Should gateway diagnostics expose selected provider/model to agents, or only to operators?
• Should prompt-aware routing use Light-Rule first, a dedicated classifier, or both?
• How should provider quota information be collected for cloud providers that do not expose uniform quota APIs?

Decision

Use the LLM gateway as the single model provider endpoint for enterprise agents. light-agent stays single-provider from its own point of view. The gateway owns multiple upstream providers, route selection, fallback, credentials, policy, audit, and observability.

WebSocket Router

Status

Phases 1, 2, and 3 are implemented. Phase 1 added configuration parsing, Java-compatible pathPrefixService normalization, route resolution, and upstream URI cleanup in light-pingora. Phase 2 wired the websocket handler into light-gateway with WebSocket upgrade detection, discovery-based upstream selection, request context storage, and upstream header/query cleanup. Phase 3 added a real gateway-to-backend WebSocket integration test for text, binary, close, subprotocol, and header behavior.

Purpose

The Java light-websocket-4j websocket-router module routes WebSocket traffic through a gateway or sidecar. A client connects to the gateway, the router resolves the downstream service from headers, query parameters, or path prefix configuration, and the gateway connects to the target WebSocket service.

In light-fabric this should be a light-pingora traffic handler activated by light-gateway through handler.yml. The same light-gateway binary can link the WebSocket router implementation, while each product decides whether it runs by including the websocket handler and websocket-router.yml configuration from config-server.

The Rust implementation should preserve the Java routing semantics and most of the Java configuration shape, but it should not copy Java's enabled flag or frame-bridging architecture. Pingora already supports HTTP/1 upgrade proxying, so the first implementation should resolve the target and let Pingora tunnel the upgraded connection.

Goals

• Add a Java-compatible WebSocket router to frameworks/light-pingora.
• Activate the router with the existing websocket handler id in apps/light-gateway.
• Keep the Java websocket-router routing configuration recognizable: defaultProtocol, defaultEnvTag, and pathPrefixService.
• Allow websocket-router.pathPrefixService to be injected by config-server at startup the same way other handler-specific config is injected.
• Resolve downstream services from header, query parameter, or longest path prefix.
• Reuse the existing light-gateway discovery and upstream selection model.
• Preserve WebSocket handshake headers and pass normal agent/browser headers through to the downstream service.
• Register the router configuration with the module registry and support the same reload model as other light-pingora handler configs.
• Keep the design suitable for gateway, sidecar, and BFF deployments.

Non-Goals

• Do not implement a separate WebSocket server framework in light-fabric.
• Do not terminate and re-create WebSocket frames in the first phase.
• Do not multiplex multiple client WebSocket sessions over one downstream connection.
• Do not support HTTP/2 extended CONNECT for WebSocket in the first phase.
• Do not use Rust dynamic plugins or inventory for WebSocket route registration.
• Do not create a separate gateway binary for WebSocket routing.
• Do not use enabled in websocket-router.yml. The handler is active when handler.yml includes websocket in the matched execution chain.

Resolved Decisions

• Activation is controlled only by handler.yml. If a matched chain includes websocket, the router is enabled for that request.
• websocket-router.yml should not contain enabled.
• WebSocket-specific controls should cover both request/upgrade rate and active upgraded connection count.
• The first implementation should use Pingora HTTP/1 upgrade passthrough, not a frame-aware WebSocket bridge.
• Invalid websocket-router.yml configuration should fail startup. Invalid reloads should be rejected while the last valid runtime state keeps serving existing traffic.

Java Behavior To Map

Java configuration includes enabled, but the Rust target config removes it:

# Light websocket router configuration
defaultProtocol: ${websocket-router.defaultProtocol:http}
defaultEnvTag: ${websocket-router.defaultEnvTag:}
pathPrefixService: ${websocket-router.pathPrefixService:}
preserveRoutingHeaders: ${websocket-router.preserveRoutingHeaders:false}
idleTimeoutMs: ${websocket-router.idleTimeoutMs:3600000}
maxConnectionDurationMs: ${websocket-router.maxConnectionDurationMs:}
maxActiveConnections: ${websocket-router.maxActiveConnections:}
maxUpgradeRequestsPerSecond: ${websocket-router.maxUpgradeRequestsPerSecond:}

The Java enabled field is intentionally not carried forward. In Rust, the handler chain is the activation contract. Removing websocket from a path or default chain disables WebSocket routing for that path.

Production controls are optional. idleTimeoutMs defaults to one hour; blank or zero values disable the matching control. preserveRoutingHeaders defaults to false, so routing-only Service-Id, service_id, and serviceId headers are stripped before the upstream handshake unless a backend explicitly needs them.

pathPrefixService accepts three forms:

pathPrefixService:
  /chat:
    serviceId: com.networknt.llmchat-1.0.0
    protocol: http
    envTag: dev

pathPrefixService:
  /chat: com.networknt.llmchat-1.0.0

pathPrefixService: {"/chat":{"serviceId":"com.networknt.llmchat-1.0.0","protocol":"http","envTag":"dev"}}

The Java handler resolves the downstream service in this order:

1. Header: first non-blank value from Service-Id, service_id, or serviceId.
2. Query parameter: first non-blank value from service_id or serviceId.
3. Path prefix: pathPrefixService match against the request path.

If a target is found, query parameters can override the target protocol and environment tag:

• protocol
• env_tag
• envTag

The Java handler removes router-only query parameters before connecting to the downstream service:

• protocol
• service_id
• serviceId
• env_tag
• envTag

The Java implementation accepts client WebSocket subprotocols, opens a new JDK WebSocket client connection to the downstream service, forwards Authorization, forwards the selected subprotocols, and then bridges text and binary frames in both directions.

Rust Architecture

Add the WebSocket router to light-pingora because it is a Pingora gateway traffic handler.

Proposed module:

frameworks/light-pingora/src/websocket.rs

Primary types:

#![allow(unused)]
fn main() {
pub struct WebSocketRouterConfig {
    pub default_protocol: String,
    pub default_env_tag: Option<String>,
    pub path_prefix_service: BTreeMap<String, WebSocketServiceTarget>,
}

pub struct WebSocketServiceTarget {
    pub service_id: String,
    pub protocol: String,
    pub env_tag: Option<String>,
}

pub struct WebSocketRouteDecision {
    pub service_id: String,
    pub protocol: String,
    pub env_tag: Option<String>,
    pub upstream_path_and_query: String,
}
}

The serde layer should accept Java field names through aliases:

• defaultProtocol
• defaultEnvTag
• pathPrefixService
• serviceId
• envTag

Use websocket-router.yml as the preferred Rust file name. Accept websocket-router.yaml as a compatibility fallback.

Config Normalization

Normalize pathPrefixService at load time:

raw config
  -> validate defaultProtocol/defaultEnvTag
  -> parse pathPrefixService YAML map, JSON string map, or legacy key/value string
  -> apply defaults to entries missing protocol or envTag
  -> sort prefixes by length for longest-prefix matching
  -> build Arc<WebSocketRouterState>

An invalid entry should fail config loading instead of being ignored silently. This is stricter than Java and is safer for remote config delivered by config-server.

Handler Registration

apps/light-gateway already reserves the websocket handler id as a traffic handler. The implementation should attach that id to the WebSocket router runtime:

handlers:
  - correlation
  - metrics
  - jwt
  - limit
  - websocket

paths:
  - path: /chat
    method: GET
    exec:
      - correlation
      - metrics
      - jwt
      - limit
      - websocket

The router should only run for chains that include websocket. This lets a BFF serve static SPA assets, REST APIs, MCP, JSON-RPC, and WebSocket endpoints from the same gateway binary with path-specific handler chains.

Request Flow

The target flow should be:

client request
  -> handler.yml path/chain match
  -> cross-cutting request handlers
  -> websocket handler
       -> verify WebSocket upgrade
       -> resolve service target
       -> strip router-only query parameters
       -> store WebSocketRouteDecision in request context
  -> Pingora upstream_peer selects discovered target
  -> Pingora upstream_request_filter preserves WebSocket handshake headers
  -> Pingora proxies the HTTP/1 upgraded stream
  -> response/metrics handlers observe completion

The router should not read the request body and should not buffer WebSocket messages. Once the request is upgraded, Pingora owns the tunnel.

Upgrade Detection

The handler should require the normal WebSocket handshake:

• method GET
• Connection contains upgrade
• Upgrade equals websocket
• Sec-WebSocket-Key exists
• HTTP version is compatible with HTTP/1 upgrade

If the websocket handler is selected by handler.yml but the request is not a WebSocket upgrade, return 426 Upgrade Required.

HTTP/2 extended CONNECT can be considered later, but should not block the first implementation.

Target Resolution

Target resolution should match Java precedence:

1. service id header
2. service id query parameter
3. pathPrefixService longest-prefix match

Header names:

Service-Id
service_id
serviceId

Query names:

service_id
serviceId
protocol
env_tag
envTag

For path-prefix matches, use the request path without the query string. When multiple prefixes match, choose the longest prefix.

The resolved protocol should be http or https. Conceptually this maps to ws or wss, but Pingora should still connect to the upstream as HTTP or HTTPS and then perform the WebSocket upgrade.

Header And Query Policy

Because the Rust implementation should use Pingora upgrade passthrough, it should preserve the original handshake headers:

• Upgrade
• Connection
• Sec-WebSocket-Key
• Sec-WebSocket-Version
• Sec-WebSocket-Protocol
• Sec-WebSocket-Extensions
• Authorization
• cookies
• normal agent/browser headers

The router should strip only router-control query parameters from the upstream URI:

• protocol
• service_id
• serviceId
• env_tag
• envTag

The service-id routing headers should be removed before the upstream request by default:

• Service-Id
• service_id
• serviceId

This keeps gateway routing controls separate from backend application headers. If a backend later needs these headers, add an explicit config option rather than leaking them by default.

Discovery And Upstream Selection

The WebSocket router should reuse the same discovery/runtime model as router.yml and the existing Pingora proxy flow.

Resolved target:

protocol + serviceId + envTag

Discovery returns an upstream HTTP or HTTPS endpoint. upstream_peer creates the Pingora peer:

• http: non-TLS upstream
• https: TLS upstream with normal SNI/hostname handling

For the first implementation, require HTTP/1.1 to the backend for WebSocket upgrade. HTTP/2 WebSocket tunneling can be a later feature.

Error Handling

Errors should be returned before the connection is upgraded: