Merge pull request #128 from smartboxgroup/feature/response-format-option

New response_format and request_fallback parameters

Author: campru

Components/WebService/Rest/RestConfigurableProducer.php

@@ -39,6 +39,7 @@ class RestConfigurableProducer extends AbstractWebServiceProducer implements Htt
     const VALIDATION_DISPLAY_MESSAGE = 'display_message';
     const VALIDATION_RECOVERABLE = 'recoverable';
     const REQUEST_EXPECTED_RESPONSE_TYPE = 'response_type';
+    const REQUEST_EXPECTED_RESPONSE_FORMAT = 'response_format';
 
     /**
      * @param $options
@@ -112,6 +113,7 @@ protected function request(ClientInterface $client, array $stepActionParams, arr
             self::VALIDATION,
             self::REQUEST_QUERY_PARAMETERS,
             self::REQUEST_BASE_URI,
+            self::REQUEST_EXPECTED_RESPONSE_FORMAT
         ]);
 
         $stepParamsResolver->setAllowedValues(self::REQUEST_HTTP_VERB, ['GET', 'POST', 'PUT', 'DELETE', 'PATCH']);
@@ -199,14 +201,19 @@ protected function request(ClientInterface $client, array $stepActionParams, arr
                     $responseBody = $this->getSerializer()->deserialize(
                         $responseContent,
                         $params[self::REQUEST_EXPECTED_RESPONSE_TYPE],
-                        $encoding
+                        $params[self::REQUEST_EXPECTED_RESPONSE_FORMAT] ?? $encoding
                     );
                 } catch (RuntimeException $e) {
                     // Assume that the exception is one of the JSON exceptions that will kill the workers
                     if (RestConfigurableProtocol::ENCODING_JSON === $encoding && (JSON_ERROR_SYNTAX != json_last_error())) {
                         throw new UnexpectedValueException($e->getMessage());
                     }
-                    // if it cannot parse the response fallback to the textual content of the body
+
+                    if (false === $endpointOptions[RestConfigurableProtocol::OPTION_RESPONSE_FALLBACK_ON_ERROR]) {
+                        throw $e;
+                    }
+
+                    trigger_error('Falling back to the original response payload when the deserialization fails and a custom response format isn\'t defined will throw an exception in v3.', E_USER_DEPRECATED);
                     $responseBody = $responseContent;
                 }
             }

Components/WebService/Rest/RestConfigurableProtocol.php

@@ -15,6 +15,8 @@ class RestConfigurableProtocol extends ConfigurableWebserviceProtocol implements
     const OPTION_HEADERS = 'headers';
     const OPTION_AUTH = 'authentication';
     const OPTION_ENCODING = 'encoding';
+    /** @deprecated: Will be removed on next major version. Fallback will not happen in v3. */
+    const OPTION_RESPONSE_FALLBACK_ON_ERROR = 'response_fallback';
 
     const ENCODING_JSON = 'json';
     const ENCODING_XML = 'xml';
@@ -58,6 +60,7 @@ public function configureOptionsResolver(OptionsResolver $resolver)
             self::OPTION_HEADERS => [],
             self::OPTION_AUTH => '',
             self::OPTION_ENCODING => self::ENCODING_JSON,
+            self::OPTION_RESPONSE_FALLBACK_ON_ERROR => true,
         ]);
 
         $resolver->setRequired([
@@ -72,6 +75,7 @@ public function configureOptionsResolver(OptionsResolver $resolver)
         $resolver->setAllowedTypes(self::OPTION_AUTH, ['string', 'null']);
         $resolver->setAllowedTypes(self::OPTION_ENCODING, ['string']);
         $resolver->setAllowedValues(self::OPTION_ENCODING, [self::ENCODING_JSON, self::ENCODING_XML]);
+        $resolver->setAllowedTypes(self::OPTION_RESPONSE_FALLBACK_ON_ERROR, ['boolean']);
     }
 
     /**

Docs/architecture/decisions/001 - amqp.md Docs/architecture/decisions/001-amqp.mdDocs/architecture/decisions/001 - amqp.md renamed to Docs/architecture/decisions/001-amqp.md

@@ -0,0 +1,32 @@
+# 2. Deprecate the response fallback on the RestConfigurableProducer class
+
+Date: 2020-05-08
+
+## Status
+
+Accepted
+
+## Context
+
+Currently the RestConfigurableProducer will pass the payload received from the target system to the serializer. If this one fails, it will catch the exception, fallback to the original response, **and continue the execution**.
+
+This was done to allow certain APIs to return a non-deserializable response while still being able to continue the execution, either **by ignoring the payload** (i.e.: when the response code is enough) or to evaluate it to something else.
+
+This makes the evaluator vulnerable, as it has no guarantee that what it will expect is something **that can be evaluated**.
+
+Due to the fallback is present by default, one endpoint **could randomly fail** if the target system decides to send back a response in a format that is not expected by the application.
+
+## Decision
+
+We decided to deprecate the response fallback in this version and remove it **in the next major version**. 
+
+A new parameter was introduced in the `RestConfigurableProducer` (`response_format`) that will define the expected response format, and this format is passed to the deserialize function to instantiate the appropriate visitor. For example, a PlainTextVisitor could be implemented to process non-JSON responses while still producing **a evaluable object**. By default, if `response_format` is not setup, `encoding` will be passed.
+
+## Consequences
+
+In order to introduce this change in a backwards compatible way, a new boolean option was introduced in the `RestConfigurableProtocol` (`response_fallback`) that will prevent the fallback. Setting it to `false` **will throw an exception** when the payload cannot be deserialized.
+
+## Metadata
+Authors: @andres.rey
+
+People involved: @david.camprubi