fix(aws-apigateway): deployment snapshots, stage variables, method and deploy validation

[NitinKumar004]

Summary

Work item A1 for REST API Gateway (v1). A deployed stage now behaves like it does on AWS.

Deployment snapshots

• CreateDeployment deep-copies the resource, method and integration tree. A stage serves its deployment's copy. Edits to the live API stay invisible until you redeploy.
• UpdateStage /deploymentId re-points a stage at an older deployment's tree, so rollback works.
• DeleteDeployment drops the captured tree.
• Redeploying to an existing stage keeps its description and variables and merges any new variables. Before this change the stage was replaced outright. CreateDeployment now accepts stageDescription and variables.
• GetDeployment?embed=apisummary returns the captured apiSummary (path, method, authorizationType, apiKeyRequired).
• Persist covers the trees (deploymentTrees in the snapshot). Older snapshots have no trees, so each deployment falls back to a copy of the restored live tree.

Stage variables

• ${stageVariables.x} in a Lambda integration URI is resolved per stage on invoke.
• The 1.0 proxy event carries stageVariables.
• A variable change applies without a redeploy, as on AWS.

Validation, with the messages AWS returns

• CreateDeployment: an API with no methods gives 400 "The REST API doesn't contain any methods". A method with no integration gives 400 "No integration defined for method". A bad stage name is also rejected.
• PutMethod: the verb must be GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS or ANY. Anything else gives 400 "Invalid HTTP method specified". A second PutMethod gives 409 "Method already exists for this resource".
• PutIntegration:
  • the type must be one of the enum values;
  • non-MOCK types need an httpMethod ("Enumeration value for HttpMethod must be non-empty");
  • HTTP types need an http(s) URI, and stage variables are allowed in the host;
  • AWS types need an arn:aws:apigateway: URI with a path or action;
  • AWS_PROXY only targets Lambda or Firehose.
• CreateStage: stage names allow only a-zA-Z0-9_- (at most 128). A duplicate gives 409 "Stage already exists". An unknown deployment gives 404 "Invalid Deployment identifier specified".
• Not-found messages for resources, methods and integrations now match AWS.

Wire fixes found in e2e

• The PutIntegration backend method travels as httpMethod in the body (the model's locationName). The handler read integrationHttpMethod, so the aws CLI and Terraform integration methods were silently dropped.
• RestApi responses carry apiStatus: AVAILABLE. AWS provider 6.x waits on that field after CreateRestApi and failed without it.
• GetResources and GetResource list methods by name only ({"GET": {}}) unless ?embed=methods asks for the full Method objects.

§3.4 pin test

• TestExecuteAPIHostForV2APIServedByV1UntilV2DataPlane pins today's behaviour: an HTTP API id on an execute-api host gets 403 {"message":"Missing Authentication Token"} from the v1 handler. A7b replaces it.
• No v2 behaviour changes here.

Tests

• The new provider and wire tests failed on the old code and pass now: snapshot gating, rollback, stage variables, redeploy merge, each validation, apiSummary, persist round trip, embed and the wire errors.
• Real-user e2e against cloudemu serve:
  • aws CLI: MOCK and HTTP-with-stage-variable integrations, deploy, execute-api invoke, a live edit without redeploy (stage unchanged), redeploy, rollback, and every error case.
  • Terraform (rest_api, resource, method, integration, deployment, stage with variables): apply, plan clean, update of the variable and the deployment trigger, plan clean, destroy.

Tracker

Closes A1 (plan B rows: PutMethod FOO accepted, CreateDeployment with zero methods, GetResources ignores embed, deployment immutability, stage variables, ${stageVariables} in the Lambda URI).

Deferred

• Invoking MOCK and HTTP integrations still returns 502. MOCK needs integration responses and templates (A2). The outbound HTTP client, including ${stageVariables} in HTTP URIs at invoke time, is A3.
• The stage variable name and value character rules, plus the timeoutInMillis range check, are not enforced yet.
• authorizationType values are not validated. That fits with the authorizer work (A5a/A5b).