Add configurable debug mode (#93)

Author: klimov-paul

README.md

@@ -130,6 +130,36 @@ mapping_aware_service:
   tags: ['json_rpc_http_server.method_aware']
 ```
 
+## Debug mode
+
+You can setup 'debug' mode for the JSON-RPC server, which allows display of verbose error information within the response JSON body.
+This information contains actual exception class name, code, message and stack trace.
+
+> Note: you should never enable 'debug' mode in 'production' environment, since it will expose vital internal information to the API consumer.
+
+Configuration example:
+
+```yaml
+# file 'config/packages/json_rpc.yaml'
+json_rpc_http_server:
+  endpoint: '/json-rpc'
+  debug:
+    enabled: false
+    max_trace_size: 10
+    show_trace_arguments: true
+    simplify_trace_arguments: true
+
+when@dev:
+  json_rpc_http_server:
+    debug:
+      enabled: true
+
+when@test:
+  json_rpc_http_server:
+    debug:
+      enabled: true
+```
+
 ## Contributing
 
 See [contributing note](./CONTRIBUTING.md)

composer.json

@@ -38,7 +38,7 @@
     "symfony/event-dispatcher-contracts": "^1.0 || ^2.0 || ^3.0",
     "symfony/http-foundation": "^4.4 || ^5.4 || ^6.0",
     "symfony/http-kernel": "^4.4 || ^5.4 || ^6.0",
-    "yoanm/jsonrpc-server-sdk": "^3.0"
+    "yoanm/jsonrpc-server-sdk": "^3.3"
   },
   "require-dev": {
     "behat/behat": "^3.9.0",

src/DependencyInjection/Configuration.php

@@ -22,6 +22,30 @@ public function getConfigTreeBuilder()
                     ->treatNullLike(self::DEFAULT_ENDPOINT)
                     ->defaultValue(self::DEFAULT_ENDPOINT)
                 ->end()
+                ->arrayNode('debug')
+                    ->addDefaultsIfNotSet()
+                    ->children()
+                        ->booleanNode('enabled')
+                            ->info(
+                                'Whether to render debug information on error or not (should NOT be enabled on prod)'
+                            )
+                            ->defaultFalse()
+                        ->end()
+                        ->integerNode('max_trace_size')
+                            ->info('Max debug trace size')
+                            ->min(0)
+                            ->defaultValue(10)
+                        ->end()
+                        ->booleanNode('show_trace_arguments')
+                            ->info('Whether to render debug stack trace arguments or not')
+                            ->defaultValue(true)
+                        ->end()
+                        ->booleanNode('simplify_trace_arguments')
+                            ->info('Whether to simplify representation of debug stack trace arguments or not')
+                            ->defaultValue(true)
+                        ->end()
+                    ->end()
+                ->end()
             ->end()
         ;
 

src/DependencyInjection/JsonRpcHttpServerExtension.php

@@ -14,7 +14,7 @@
 use Yoanm\JsonRpcServer\Domain\JsonRpcMethodAwareInterface;
 
 /**
- * Class JsonRpcHttpServerExtension
+ * @see \Yoanm\SymfonyJsonRpcHttpServer\DependencyInjection\Configuration
  */
 class JsonRpcHttpServerExtension implements ExtensionInterface, CompilerPassInterface
 {
@@ -66,7 +66,8 @@ public function process(ContainerBuilder $container)
     {
         $this->bindJsonRpcServerDispatcher($container);
         $this->bindValidatorIfDefined($container);
-        $this->binJsonRpcMethods($container);
+        $this->bindJsonRpcMethods($container);
+        $this->bindDebug($container);
     }
 
     /**
@@ -102,17 +103,19 @@ private function compileAndProcessConfigurations(array $configs, ContainerBuilde
         $configuration = new Configuration();
         $config = (new Processor())->processConfiguration($configuration, $configs);
 
-        $httpEndpointPath = $config['endpoint'];
+        $container->setParameter(self::ENDPOINT_PATH_CONTAINER_PARAM_ID, $config['endpoint']);
 
-        $container->setParameter(self::ENDPOINT_PATH_CONTAINER_PARAM_ID, $httpEndpointPath);
+        foreach ($config['debug'] as $name => $value) {
+            $container->setParameter(self::EXTENSION_IDENTIFIER.'.debug.'.$name, $value);
+        }
     }
 
     /**
      * @param ContainerBuilder $container
      */
     private function bindJsonRpcServerDispatcher(ContainerBuilder $container) : void
     {
-        $dispatcherRef = new Reference('json_rpc_http_server.dispatcher.server');
+        $dispatcherRef = new Reference(self::EXTENSION_IDENTIFIER.'.dispatcher.server');
         $dispatcherAwareServiceList = $container->findTaggedServiceIds(self::JSONRPC_SERVER_DISPATCHER_AWARE_TAG);
         foreach ($dispatcherAwareServiceList as $serviceId => $tagAttributeList) {
             $definition = $container->getDefinition($serviceId);
@@ -149,7 +152,7 @@ private function bindValidatorIfDefined(ContainerBuilder $container) : void
     /**
      * @param ContainerBuilder $container
      */
-    private function binJsonRpcMethods(ContainerBuilder $container) : void
+    private function bindJsonRpcMethods(ContainerBuilder $container) : void
     {
         $mappingAwareServiceDefinitionList = $this->findAndValidateMappingAwareDefinitionList($container);
 
@@ -166,7 +169,7 @@ private function binJsonRpcMethods(ContainerBuilder $container) : void
 
         // Service locator for method resolver
         // => first argument is an array of wanted service with keys as alias for internal use
-        $container->getDefinition('json_rpc_http_server.service_locator.method_resolver')
+        $container->getDefinition(self::EXTENSION_IDENTIFIER.'.service_locator.method_resolver')
             ->setArgument(0, $methodMappingList);
     }
 
@@ -223,4 +226,12 @@ private function checkMethodAwareServiceIdList(
             ));
         }
     }
+
+    private function bindDebug(ContainerBuilder $container) : void
+    {
+        if ($container->getParameter(self::EXTENSION_IDENTIFIER.'.debug.enabled')) {
+            $container->getDefinition('json_rpc_server_sdk.app.serialization.jsonrpc_response_normalizer')
+                ->addArgument(new Reference('json_rpc_server_sdk.app.serialization.jsonrpc_response_error_normalizer'));
+        }
+    }
 }

src/JsonRpcHttpServerBundle.php

@@ -4,7 +4,7 @@
 use Symfony\Component\HttpKernel\Bundle\Bundle;
 
 /**
- * Class JsonRpcHttpServerBundle
+ * @see \Yoanm\SymfonyJsonRpcHttpServer\DependencyInjection\JsonRpcHttpServerExtension
  */
 class JsonRpcHttpServerBundle extends Bundle
 {

src/Resources/config/sdk.services.app.yaml

@@ -1,5 +1,5 @@
 services:
-  #Serialization
+  # Serialization
   json_rpc_server_sdk.app.serialization.jsonrpc_request_denormalizer:
       class: Yoanm\JsonRpcServer\App\Serialization\JsonRpcRequestDenormalizer
 
@@ -22,7 +22,7 @@ services:
         - '@json_rpc_server_sdk.app.serialization.jsonrpc_call_dernormalizer'
         - '@json_rpc_server_sdk.app.serialization.jsonrpc_call_response_normalizer'
 
-  #Handlers
+  # Handlers
   json_rpc_server_sdk.app.handler.jsonrpc_request:
       class: Yoanm\JsonRpcServer\App\Handler\JsonRpcRequestHandler
       arguments:
@@ -39,3 +39,11 @@ services:
   # Creator
   json_rpc_server_sdk.app.creator.response:
       class: Yoanm\JsonRpcServer\App\Creator\ResponseCreator
+
+  # Debug
+  json_rpc_server_sdk.app.serialization.jsonrpc_response_error_normalizer:
+      class: Yoanm\JsonRpcServer\App\Serialization\JsonRpcResponseErrorNormalizer
+      arguments:
+        - '%json_rpc_http_server.debug.max_trace_size%'
+        - '%json_rpc_http_server.debug.show_trace_arguments%'
+        - '%json_rpc_http_server.debug.simplify_trace_arguments%'

tests/Functional/DependencyInjection/ConfigFilesTest.php

@@ -11,6 +11,7 @@
 use Yoanm\JsonRpcServer\App\Serialization\JsonRpcCallSerializer;
 use Yoanm\JsonRpcServer\App\Serialization\JsonRpcRequestDenormalizer;
 use Yoanm\JsonRpcServer\App\Serialization\JsonRpcResponseNormalizer;
+use Yoanm\JsonRpcServer\App\Serialization\JsonRpcResponseErrorNormalizer;
 use Yoanm\JsonRpcServer\Infra\Endpoint\JsonRpcEndpoint;
 use Yoanm\SymfonyJsonRpcHttpServer\DependencyInjection\JsonRpcHttpServerExtension;
 use Yoanm\SymfonyJsonRpcHttpServer\Dispatcher\SymfonyJsonRpcServerDispatcher;
@@ -100,6 +101,11 @@ public function provideSDKAppServiceIdAndClass()
                 'serviceClassName' => ResponseCreator::class,
                 'public' => false,
             ],
+            'SDK - App - Response error normalizer' => [
+                'serviceId' => 'json_rpc_server_sdk.app.serialization.jsonrpc_response_error_normalizer',
+                'serviceClassName' => JsonRpcResponseErrorNormalizer::class,
+                'public' => false,
+            ],
         ];
     }
 

tests/Functional/DependencyInjection/JsonRpcHttpServerExtensionTest.php

@@ -185,4 +185,22 @@ public function testShouldThowAnExceptionIfMethodAwareServiceDoesNotImplementRig
 
         $this->loadContainer();
     }
+
+    public function testShouldAddDebugResponseErrorNormalizerIfDebugModeEnabled()
+    {
+        $this->loadContainer([
+            'debug' => [
+                'enabled' => true,
+            ]
+        ]);
+
+        // Assert response normalizer has responseErrorNormalizer as first argument
+        $this->assertContainerBuilderHasServiceDefinitionWithArgument(
+            'json_rpc_server_sdk.app.serialization.jsonrpc_response_normalizer',
+            0,
+            new Reference('json_rpc_server_sdk.app.serialization.jsonrpc_response_error_normalizer'),
+        );
+
+        $this->assertEndpointIsUsable();
+    }
 }