feat: rework names and validation

Author: alekseytupichenkov

README.md

@@ -1,17 +1,18 @@
 # Schema Context Bundle
 
-The **SchemaContextBundle** provides a lightweight way to manage dynamic schema context across your Symfony application, especially useful for multi-tenant setups. It allows schema resolution based on request headers and propagates schema information through Symfony Messenger.
+The **SchemaContextBundle** provides a robust way to manage dynamic schema context across your Symfony application, especially useful for multi-tenant setups. It extracts schema information from W3C standard baggage headers (or Symfony Messenger Stamps), validates schema changes based on environment configuration, and propagates schema context throughout your application, including HTTP clients and Symfony Messenger queues.
 
 ---
 
 ## Features
 
-- Extracts tenant schema param from baggage request header.
+- Extracts tenant schema param from W3C standard `baggage` request header.
 - Stores schema and baggage context in a global `BaggageSchemaResolver`.
+- Validates schema changes based on environment configuration to prevent accidental schema mismatches.
 - Injects schema and baggage info into Messenger messages via a middleware.
 - Rehydrates schema and baggage on message consumption via a middleware.
-- Provide decorator for Http clients to propagate baggage header
-- Optional: Adds baggage context to Monolog log records via a processor
+- Provide decorator for Http clients to propagate baggage header.
+- Optional: Adds baggage context to Monolog log records via a processor.
 
 ---
 
@@ -35,18 +36,28 @@ Add this config to `config/packages/schema_context.yaml`:
 
 ```yaml
 schema_context:
-    app_name: '%env(APP_NAME)%' # Application name
-    header_name: 'X-Tenant' # Request header to extract schema name
-    default_schema: 'public' # Default schema to fallback to
-    allowed_app_names: ['develop', 'staging', 'test'] # App names where schema context is allowed to change
+    environment_name: '%env(APP_ENV)%' # Current environment name (example: 'develop')
+    header_name: 'X-Tenant' # Key name in baggage header to extract schema name
+    environment_schema: '%env(ENVIRONMENT_SCHEMA)%' # The schema for this environment (example: 'public')
+    overridable_environments: ['develop', 'staging', 'test'] # Environments where schema can be overridden via baggage header or Symfony Messenger stamp
 ```
-### 2. Set Environment Parameters
-If you're using .env, define the app name:
+
+**Configuration parameters:**
+- `environment_name`: The name of the current environment. Best practice is to use `'%env(APP_ENV)%'` to match Symfony's environment.
+- `environment_schema`: The schema for this environment.
+- `header_name`: The key name in the baggage header used to extract the schema value.
+- `overridable_environments`: List of environment names where schema can be overridden via baggage header or Symfony Messenger stamp.
 
 ```env
-APP_NAME=develop
+APP_ENV=develop
+ENVIRONMENT_SCHEMA=public
 ```
 
+### 3. Schema Override Protection
+The bundle includes protection against accidental schema changes in production environments:
+- In **non-overridable environments** (e.g., `production`): The schema is always fixed to `environment_schema`. Any attempt to override it via baggage header will throw `EnvironmentSchemaMismatchException`.
+- In **overridable environments** (e.g., `develop`, `staging`): The schema can be dynamically changed via baggage header for testing and development purposes.
+
 ## Usage
 
 ```php
@@ -60,6 +71,36 @@ public function index(BaggageSchemaResolver $schemaResolver)
 }
 ```
 
+### Baggage Header Format
+
+The bundle uses W3C standard `baggage` header format. Example request:
+
+```http
+GET /api/endpoint HTTP/1.1
+Host: example.com
+baggage: X-Tenant=tenant_a,user-id=12345,trace-id=abc123
+```
+
+The bundle will extract the schema value from the baggage header using the key specified in `header_name` configuration.
+
+## Exception Handling
+
+### EnvironmentSchemaMismatchException
+
+The bundle throws `EnvironmentSchemaMismatchException` when:
+- The environment is **not** in the `overridable_environments` list
+- A request tries to set a schema via baggage header that differs from `environment_schema`
+
+This exception prevents accidental schema changes in production/staging/etc. environments. Example error message:
+
+```
+Schema mismatch in "production" environment: expected "public", got "tenant_a". Allowed override environments: [develop, staging, test].
+```
+
+**How to handle:**
+- In production/staging/etc.: ensure clients don't send schema baggage headers, or send the correct environment schema
+- In development: add your environment to `overridable_environments` list if you need to test different schemas
+
 ## Baggage-Aware HTTP Client
 Decorate your http client in your service configuration:
 ```yaml

config/services.yaml

@@ -5,6 +5,10 @@ services:
     public: false
 
   Macpaw\SchemaContextBundle\Service\BaggageSchemaResolver:
+    arguments:
+      $environmentSchema: '%schema_context.environment_schema%'
+      $environmentName: '%schema_context.environment_name%'
+      $schemaOverridableEnvironments: '%schema_context.overridable_environments%'
     public: true
     shared: true
 
@@ -16,14 +20,9 @@ services:
     arguments:
       $baggageSchemaResolver: '@Macpaw\SchemaContextBundle\Service\BaggageSchemaResolver'
       $schemaRequestHeader: '%schema_context.header_name%'
-      $defaultSchema: '%schema_context.default_schema%'
-      $appName: '%schema_context.app_name%'
-      $allowedAppNames: '%schema_context.allowed_app_names%'
     tags:
       - { name: kernel.event_subscriber }
 
   Macpaw\SchemaContextBundle\Messenger\Middleware\BaggageSchemaMiddleware:
-    arguments:
-      $defaultSchema: '%schema_context.default_schema%'
     tags:
       - { name: messenger.middleware }

src/DependencyInjection/Configuration.php

@@ -16,9 +16,9 @@ public function getConfigTreeBuilder(): TreeBuilder
         $treeBuilder->getRootNode()
             ->children()
                 ->scalarNode('header_name')->defaultValue('X-Schema')->end()
-                ->scalarNode('default_schema')->defaultValue('public')->end()
-                ->scalarNode('app_name')->isRequired()->cannotBeEmpty()->end()
-                ->arrayNode('allowed_app_names')
+                ->scalarNode('environment_name')->defaultValue('public')->end()
+                ->scalarNode('environment_schema')->isRequired()->cannotBeEmpty()->end()
+                ->arrayNode('overridable_environments')
                     ->scalarPrototype()->end()
                     ->defaultValue([])
                 ->end()

src/DependencyInjection/SchemaContextCompilerPass.php

@@ -33,7 +33,6 @@ public function process(ContainerBuilder $container): void
         // Inject the inner/original factory + your resolver
         $def->setArgument('$decoratedFactory', new Reference(self::DECORATOR_ID . '.inner'));
         $def->setArgument('$baggageSchemaResolver', new Reference(BaggageSchemaResolver::class));
-        $def->setArgument('$defaultSchema', $container->getParameter('schema_context.default_schema'));
 
         $container->setDefinition(self::DECORATOR_ID, $def);
     }

src/DependencyInjection/SchemaContextExtension.php

@@ -17,9 +17,9 @@ public function load(array $configs, ContainerBuilder $container)
         $config = $this->processConfiguration($configuration, $configs);
 
         $container->setParameter('schema_context.header_name', $config['header_name']);
-        $container->setParameter('schema_context.default_schema', $config['default_schema']);
-        $container->setParameter('schema_context.app_name', $config['app_name']);
-        $container->setParameter('schema_context.allowed_app_names', $config['allowed_app_names']);
+        $container->setParameter('schema_context.environment_schema', $config['environment_schema']);
+        $container->setParameter('schema_context.environment_name', $config['environment_name']);
+        $container->setParameter('schema_context.overridable_environments', $config['overridable_environments']);
 
         $loader = new YamlFileLoader($container, new FileLocator(__DIR__ . '/../../config'));
 

src/EventListener/BaggageRequestListener.php

@@ -16,10 +16,6 @@ public function __construct(
         private BaggageSchemaResolver $baggageSchemaResolver,
         private BaggageCodec $baggageCodec,
         private string $schemaRequestHeader,
-        private string $defaultSchema,
-        private string $appName,
-        /** @var string[] */
-        private array $allowedAppNames,
     ) {
     }
 
@@ -30,30 +26,18 @@ public static function getSubscribedEvents(): array
 
     public function onKernelRequest(RequestEvent $event): void
     {
-        if (!$this->isAllowedAppName()) {
-            return;
-        }
-
         $request = $event->getRequest();
-        $baggage = $request->headers->get('baggage');
+        $headerBaggage = $request->headers->get('baggage');
 
+        $baggage = null;
         $schema = null;
-        if ($baggage) {
-            $baggage = $this->baggageCodec->decode($baggage);
-            $this->baggageSchemaResolver->setBaggage($baggage);
 
+        if ($headerBaggage) {
+            $baggage = $this->baggageCodec->decode($headerBaggage);
             $schema = $baggage[$this->schemaRequestHeader] ?? null;
         }
 
-        if ($schema !== null && $schema !== '') {
-            $this->baggageSchemaResolver->setSchema($schema);
-        } else {
-            $this->baggageSchemaResolver->setSchema($this->defaultSchema);
-        }
-    }
-
-    private function isAllowedAppName(): bool
-    {
-        return in_array($this->appName, $this->allowedAppNames, true);
+        $this->baggageSchemaResolver->setBaggage($baggage);
+        $this->baggageSchemaResolver->setSchema($schema);
     }
 }

src/Exception/EnvironmentSchemaMismatchException.php

@@ -0,0 +1,32 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Macpaw\SchemaContextBundle\Exception;
+
+use Exception;
+use Symfony\Component\HttpFoundation\Response;
+
+class EnvironmentSchemaMismatchException extends Exception
+{
+    /**
+     * @param string[] $schemaOverridableEnvironments
+     */
+    public function __construct(
+        string $actualSchema,
+        string $environmentSchema,
+        string $environmentName,
+        array $schemaOverridableEnvironments,
+    ) {
+        parent::__construct(
+            sprintf(
+                'Schema mismatch in "%s" environment: expected "%s", got "%s". Allowed override environments: [%s].',
+                $environmentName,
+                $environmentSchema,
+                $actualSchema,
+                implode(', ', $schemaOverridableEnvironments)
+            ),
+            Response::HTTP_INTERNAL_SERVER_ERROR
+        );
+    }
+}

src/Messenger/Middleware/BaggageSchemaMiddleware.php

@@ -17,7 +17,6 @@ class BaggageSchemaMiddleware implements MiddlewareInterface
     public function __construct(
         private BaggageSchemaResolver $baggageSchemaResolver,
         private BaggageCodec $baggageCodec,
-        private string $defaultSchema,
     ) {
     }
 
@@ -29,7 +28,7 @@ public function handle(Envelope $envelope, StackInterface $stack): Envelope
             if ($stamp instanceof BaggageSchemaStamp) {
                 $this->baggageSchemaResolver
                     ->setSchema($stamp->schema)
-                    ->setBaggage($this->baggageCodec->decode($stamp->baggage));
+                    ->setBaggage($stamp->baggage === null ? null : $this->baggageCodec->decode($stamp->baggage));
             }
 
             $result = $stack->next()->handle($envelope, $stack);
@@ -40,13 +39,11 @@ public function handle(Envelope $envelope, StackInterface $stack): Envelope
         }
 
         $schema = $this->baggageSchemaResolver->getSchema();
-        $baggage = $this->baggageCodec->encode($this->baggageSchemaResolver->getBaggage() ?? []);
+        $baggage = $this->baggageSchemaResolver->getBaggage() === null
+            ? null
+            : $this->baggageCodec->encode($this->baggageSchemaResolver->getBaggage());
 
-        if ($schema !== null && $schema !== '') {
-            $envelope = $envelope->with(new BaggageSchemaStamp($schema, $baggage));
-        } else {
-            $envelope = $envelope->with(new BaggageSchemaStamp($this->defaultSchema, $baggage));
-        }
+        $envelope = $envelope->with(new BaggageSchemaStamp($schema, $baggage));
 
         return $stack->next()->handle($envelope, $stack);
     }

src/Messenger/Stamp/BaggageSchemaStamp.php

@@ -8,7 +8,7 @@
 
 class BaggageSchemaStamp implements StampInterface
 {
-    public function __construct(public string $schema, public string $baggage)
+    public function __construct(public ?string $schema, public ?string $baggage)
     {
     }
 }

src/Messenger/Transport/DoctrineTransportFactoryDecorator.php

@@ -20,26 +20,21 @@ final class DoctrineTransportFactoryDecorator implements TransportFactoryInterfa
     public function __construct(
         private readonly TransportFactoryInterface $decoratedFactory,
         private readonly BaggageSchemaResolver $baggageSchemaResolver,
-        private readonly string $defaultSchema = 'public',
     ) {
     }
 
     public function createTransport(string $dsn, array $options, SerializerInterface $serializer): TransportInterface
     {
-        // Get current schema from BaggageSchemaResolver
         $currentSchema = $this->baggageSchemaResolver->getSchema();
 
-        // If we have a schema and it's not the default 'public' schema, modify the table name
-        if ($currentSchema !== null && $currentSchema !== $this->defaultSchema) {
-            $originalTableName = sprintf(
-                '"%s"."%s"',
-                $currentSchema,
-                $options['table_name'] ?? 'messenger_messages',
-            );
-
-            // Create transport with schema-prefixed table name
-            $options['table_name'] = $originalTableName;
-        }
+        $originalTableName = sprintf(
+            '"%s"."%s"',
+            $currentSchema,
+            $options['table_name'] ?? 'messenger_messages',
+        );
+
+        // Create transport with schema-prefixed table name
+        $options['table_name'] = $originalTableName;
 
         // Create transport with the original factory
         return $this->decoratedFactory->createTransport($dsn, $options, $serializer);