perf(serde): Compile per-shape JSON and XML serde plans with caching

.changes/nextrelease/serde-plan-cache.json

@@ -0,0 +1,7 @@
+[
+    {
+        "type": "enhancement",
+        "category": "Api",
+        "description": "Caches compiled JSON and XML serialization and parsing plans on model shapes, reducing per-request serialization and parsing overhead. Wire output and parsed results are unchanged, and plans are invalidated when a shape is mutated."
+    }
+]

src/Api/AbstractModel.php

@@ -15,6 +15,12 @@ abstract class AbstractModel implements \ArrayAccess
     /** @var array */
     protected $contextParam;
 
+    /** @var array Cached serde plans keyed by ShapePlanCache slot. */
+    protected $cachedPlans = [];
+
+    /** @var int Graph generation the cached plans were built against. */
+    protected $planGeneration = 0;
+
     /**
      * @param array    $definition Service description
      * @param ShapeMap $shapeMap   Shapemap used for creating shapes
@@ -28,6 +34,43 @@ public function __construct(array $definition, ShapeMap $shapeMap)
         }
     }
 
+    /**
+     * Get a cached serde plan for the given slot.
+     *
+     * Returns null when no plan is cached, or when the cache is stale because
+     * a related model object mutated since the plan was built.
+     *
+     * @param int $slot A ShapePlanCache slot constant.
+     *
+     * @return mixed|null
+     * @internal
+     */
+    public function getSerdePlan($slot)
+    {
+        $this->syncPlanGeneration();
+
+        return $this->cachedPlans[$slot] ?? null;
+    }
+
+    /**
+     * Cache a serde plan for the given slot and return it.
+     *
+     * Returns the plan so providers can compile and cache in one expression.
+     *
+     * @param int   $slot A ShapePlanCache slot constant.
+     * @param mixed $plan The compiled plan to cache.
+     *
+     * @return mixed The cached plan.
+     * @internal
+     */
+    public function cacheSerdePlan($slot, $plan)
+    {
+        $this->syncPlanGeneration();
+        $this->cachedPlans[$slot] = $plan;
+
+        return $plan;
+    }
+
     public function toArray()
     {
         return $this->definition;
@@ -50,6 +93,7 @@ public function offsetGet($offset)
     public function offsetSet($offset, $value)
     {
         $this->definition[$offset] = $value;
+        $this->invalidateResolvedModel();
     }
 
     /**
@@ -68,6 +112,60 @@ public function offsetExists($offset)
     public function offsetUnset($offset)
     {
         unset($this->definition[$offset]);
+        $this->invalidateResolvedModel();
+    }
+
+    /**
+     * Clear resolved child model objects cached on this instance.
+     *
+     * The base model caches no resolved children. Subclasses that memoize
+     * resolved members, elements, or shapes override this to drop them so a
+     * definition change is reflected on the next access.
+     *
+     * @return void
+     */
+    protected function clearResolvedModelCache()
+    {
+        // No resolved children on the base model.
+    }
+
+    /**
+     * Drop resolved children and cached plans after a definition mutation, then
+     * advance the graph generation so plans derived on related objects rebuild.
+     *
+     * Safe when no ShapeMap is present, which happens for mocks that construct
+     * model objects directly.
+     *
+     * @return void
+     */
+    private function invalidateResolvedModel()
+    {
+        $this->clearResolvedModelCache();
+        $this->cachedPlans = [];
+
+        if ($this->shapeMap !== null) {
+            $this->shapeMap->incrementGeneration();
+            $this->planGeneration = $this->shapeMap->getGeneration();
+        }
+    }
+
+    /**
+     * Drop cached plans when the graph generation has moved past the one they
+     * were built against.
+     *
+     * @return void
+     */
+    private function syncPlanGeneration()
+    {
+        if ($this->shapeMap === null) {
+            return;
+        }
+
+        $generation = $this->shapeMap->getGeneration();
+        if ($this->planGeneration !== $generation) {
+            $this->cachedPlans = [];
+            $this->planGeneration = $generation;
+        }
     }
 
     protected function shapeAt($key)

src/Api/ListShape.php

@@ -32,4 +32,12 @@ public function getMember()
 
         return $this->member;
     }
+
+    /**
+     * @return void
+     */
+    protected function clearResolvedModelCache()
+    {
+        $this->member = null;
+    }
 }

src/Api/MapShape.php

@@ -51,4 +51,13 @@ public function getKey()
 
         return $this->key;
     }
+
+    /**
+     * @return void
+     */
+    protected function clearResolvedModelCache()
+    {
+        $this->value = null;
+        $this->key = null;
+    }
 }

src/Api/Operation.php

@@ -11,6 +11,7 @@ class Operation extends AbstractModel
     private $errors;
     private $staticContextParams = [];
     private $contextParams;
+    private $contextParamsGeneration;
     private $operationContextParams = [];
 
     public function __construct(array $definition, ShapeMap $shapeMap)
@@ -35,6 +36,7 @@ public function __construct(array $definition, ShapeMap $shapeMap)
 
         parent::__construct($definition, $shapeMap);
         $this->contextParams = $this->setContextParams();
+        $this->contextParamsGeneration = $shapeMap->getGeneration();
     }
 
     /**
@@ -126,6 +128,14 @@ public function getStaticContextParams()
      */
     public function getContextParams()
     {
+        // Context params derive from the input shape graph, so rebuild them
+        // when any shape in the shared ShapeMap has been mutated.
+        $generation = $this->shapeMap->getGeneration();
+        if ($this->contextParams === null || $this->contextParamsGeneration !== $generation) {
+            $this->contextParams = $this->setContextParams();
+            $this->contextParamsGeneration = $generation;
+        }
+
         return $this->contextParams;
     }
 
@@ -140,12 +150,28 @@ public function getOperationContextParams(): array
         return $this->operationContextParams;
     }
 
+    /**
+     * @return void
+     */
+    protected function clearResolvedModelCache()
+    {
+        $this->input = null;
+        $this->output = null;
+        $this->errors = null;
+
+        // Context params derive from the definition and the input shape, so
+        // refresh them too. Dynamic context params rebuild on next access.
+        $this->staticContextParams = $this->definition['staticContextParams'] ?? [];
+        $this->operationContextParams = $this->definition['operationContextParams'] ?? [];
+        $this->contextParams = null;
+    }
+
     private function setContextParams()
     {
         $members = $this->getInput()->getMembers();
         $contextParams = [];
 
-        foreach($members as $name => $shape) {
+        foreach ($members as $name => $shape) {
             if (!empty($contextParam = $shape->getContextParam())) {
                 $contextParams[$contextParam['name']] = [
                     'shape' => $name,

src/Api/Parser/JsonParser.php

@@ -2,73 +2,121 @@
 namespace Aws\Api\Parser;
 
 use Aws\Api\DateTimeResult;
+use Aws\Api\Serde\Json\JsonDecodePlan;
+use Aws\Api\Serde\Json\JsonDecodePlanProvider;
+use Aws\Api\Serde\Json\JsonShapeType;
 use Aws\Api\Shape;
 
 /**
  * @internal Implements standard JSON parsing.
  */
 class JsonParser
 {
+    /** @var JsonDecodePlanProvider */
+    private $planProvider;
+
+    public function __construct()
+    {
+        $this->planProvider = new JsonDecodePlanProvider();
+    }
+
     public function parse(Shape $shape, $value)
     {
         if ($value === null) {
             return $value;
         }
 
-        switch ($shape['type']) {
-            case 'structure':
-                if (isset($shape['document']) && $shape['document']) {
-                    return $value;
-                }
+        return $this->parsePlan($this->planProvider->get($shape), $value);
+    }
+
+    /**
+     * Decodes a value using a compiled plan instead of re-reading the model.
+     *
+     * Preserves modeled member order and union handling.
+     */
+    private function parsePlan(JsonDecodePlan $plan, $value)
+    {
+        switch ($plan->type) {
+            case JsonShapeType::STRUCTURE:
                 $target = [];
-                foreach ($shape->getMembers() as $name => $member) {
-                    $locationName = $member['locationName'] ?: $name;
-                    if (isset($value[$locationName])) {
-                        $target[$name] = $this->parse($member, $value[$locationName]);
+                foreach ($plan->members as $member) {
+                    $wire = $member[JsonDecodePlan::M_WIRE];
+                    if (isset($value[$wire])) {
+                        $target[$member[JsonDecodePlan::M_SDK]] = $this->parseByType(
+                            $member[JsonDecodePlan::M_TYPE],
+                            $member[JsonDecodePlan::M_SHAPE],
+                            $member[JsonDecodePlan::M_TSFORMAT],
+                            $value[$wire]
+                        );
                     }
                 }
-                if (isset($shape['union'])
-                    && $shape['union']
-                    && is_array($value)
-                    && empty($target)
-                ) {
+                if ($plan->union && is_array($value) && empty($target)) {
                     foreach ($value as $key => $val) {
                         $target['Unknown'][$key] = $val;
                     }
                 }
                 return $target;
 
-            case 'list':
-                $member = $shape->getMember();
+            case JsonShapeType::LIST:
+                $type  = $plan->value[JsonDecodePlan::V_TYPE];
+                $shape = $plan->value[JsonDecodePlan::V_SHAPE];
+                $ts    = $plan->value[JsonDecodePlan::V_TSFORMAT];
                 $target = [];
                 foreach ($value as $v) {
-                    $target[] = $this->parse($member, $v);
+                    $target[] = $this->parseByType($type, $shape, $ts, $v);
                 }
                 return $target;
 
-            case 'map':
-                $values = $shape->getValue();
+            case JsonShapeType::MAP:
+                $type  = $plan->value[JsonDecodePlan::V_TYPE];
+                $shape = $plan->value[JsonDecodePlan::V_SHAPE];
+                $ts    = $plan->value[JsonDecodePlan::V_TSFORMAT];
                 $target = [];
                 foreach ($value as $k => $v) {
                     // null map values should not be deserialized
                     if (!is_null($v)) {
-                        $target[$k] = $this->parse($values, $v);
+                        $target[$k] = $this->parseByType($type, $shape, $ts, $v);
                     }
                 }
                 return $target;
 
-            case 'timestamp':
-                return DateTimeResult::fromTimestamp(
-                    $value,
-                    !empty($shape['timestampFormat']) ? $shape['timestampFormat'] : null
-                );
+            case JsonShapeType::TIMESTAMP:
+                return DateTimeResult::fromTimestamp($value, $plan->timestampFormat);
 
-            case 'blob':
+            case JsonShapeType::BLOB:
                 return base64_decode($value);
 
-            default:
+            default: // SCALAR, DOCUMENT
                 return $value;
         }
     }
-}
 
+    /**
+     * Decodes one member or collection element. Composite children fetch their
+     * own plan lazily; leaf types are handled inline.
+     */
+    private function parseByType(int $type, Shape $shape, ?string $tsFormat, $value)
+    {
+        // A null value is returned as-is for every shape type, so sparse
+        // list elements stay null.
+        if ($value === null) {
+            return null;
+        }
+
+        switch ($type) {
+            case JsonShapeType::STRUCTURE:
+            case JsonShapeType::LIST:
+            case JsonShapeType::MAP:
+                return $this->parsePlan($this->planProvider->get($shape), $value);
+
+            case JsonShapeType::TIMESTAMP:
+                return DateTimeResult::fromTimestamp($value, $tsFormat);
+
+            case JsonShapeType::BLOB:
+                return base64_decode($value);
+
+            default: // SCALAR, DOCUMENT
+                return $value;
+        }
+    }
+}