feat(aws-apigateway): client certificates, documentation parts and versions, account settings

[NitinKumar004]

Summary

A12b from the API Gateway build-out plan. Adds the REST API (v1) resources that sit next to the API tree: client certificates, documentation parts and versions, and the account settings. Behaviour lives in the provider; the wire handler only maps routes and shapes.

Client certificates

• POST /clientcertificates, GET /clientcertificates (position/limit paging, default 25, max 500), GET|PATCH|DELETE /clientcertificates/{id}.
• pemEncodedCertificate is a real self-signed RSA-2048 certificate with a 365-day validity. expirationDate matches its NotAfter. Only the public certificate is kept.
• PATCH allows /description only. Any other path is a BadRequest.
• Tags via PUT|GET|DELETE /tags/{arn} for client certificate and REST API ARNs. Other API Gateway ARNs (the v2 /apis tree) and other services' ARNs still fall through to their own handlers.
• A stage's /clientCertificateId must name an existing certificate (404 otherwise). Deleting a certificate that a stage still uses returns a BadRequest that names the stages.

Documentation parts

• Create, Get, List, Update and Delete, plus Import (PUT .../documentation/parts?mode=merge|overwrite&failonwarnings=).
• The location is checked against the AWS table of valid fields for each type: a field that doesn't apply is rejected, and so is a missing required name or a bad statusCode. Defaults are filled on read (path /, method and statusCode *), so an omitted field and its explicit default are the same location.
• A duplicate location is a 409 with the AWS message (Documentation part already exists for the specified location: type 'API'.).
• List filters: type, path (exact), name (substring), locationStatus (DOCUMENTED means non-empty properties).
• Import reads x-amazon-apigateway-documentation from a JSON or YAML OpenAPI body. Merge keeps the part id at a location it already has; overwrite replaces all parts. Invalid entries come back as warnings, or fail the whole import under failonwarnings.

Documentation versions

• Create snapshots the current parts. With stageName it also sets that stage's documentationVersion. Get, List (paged), Update (/description) and Delete are included.
• A stage's documentationVersion (CreateStage or /documentationVersion patch) must name an existing version. Deleting a version that a stage uses is a BadRequest.

Account

• GET /account defaults: throttle 10000 rps and burst 5000, features [UsagePlans], apiKeyVersion 4.
• PATCH /account accepts /cloudwatchRoleArn (replace or remove, must be a role ARN) and /features (add or remove UsagePlans). Throttle settings and apiKeyVersion are read-only in AWS, so patching them is a BadRequest.

Other

• Client certificates, the account, doc parts and doc versions (with their frozen parts) are all in the snapshot. Old snapshots still restore, using the account defaults.
• UpdateStage now applies its ops to a copy, so a failing op leaves the stage unchanged.
• Coverage docs regenerated.

Testing

• Provider tests: cert PEM and validity, lifecycle, paging, stage reference and in-use delete, tags; location defaults and validation, duplicates, filters, import merge/overwrite/YAML/failOnWarnings; version lifecycle and stage association; account defaults and patching; snapshot round trip. They failed to build against the old code.
• Wire tests through the full AWS server for every new route and the main error cases.
• go build ./..., then vet and go test -race on the touched packages and persist. golangci-lint --new-from-rev=origin/development reports 0 issues.
• aws CLI against serve: generated a cert, attached it to a stage, got the in-use delete error, created parts, got the duplicate and invalid-location errors, ran a merge import with a warning and a failOnWarnings import, created a doc version on the stage, updated the account, and hit the bad-role and read-only-path errors. After detaching, all deletes succeeded.
• Terraform (hashicorp/aws) with aws_api_gateway_client_certificate, aws_api_gateway_documentation_part, aws_api_gateway_documentation_version, aws_api_gateway_account, and a stage using client_certificate_id and documentation_version: apply, plan clean, update every mutable field, plan clean, destroy.

Notes

I couldn't confirm two behaviours from the AWS docs: whether deleting an in-use client certificate, or a documentation version tied to a stage, is blocked, and which error it returns. Both are blocked with a BadRequest for now. Stage tags are left for a later change.