@suss/contract-aws-apigateway 0.0.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +205 -0
- package/README.md +34 -0
- package/dist/index.cjs +585 -0
- package/dist/index.d.cts +184 -0
- package/dist/index.d.ts +184 -0
- package/dist/index.js +557 -0
- package/package.json +58 -0
package/dist/index.d.cts
ADDED
|
@@ -0,0 +1,184 @@
|
|
|
1
|
+
import { BehavioralSummary } from '@suss/behavioral-ir';
|
|
2
|
+
|
|
3
|
+
/**
|
|
4
|
+
* Reference back into the source manifest that introduced a piece of
|
|
5
|
+
* configuration. Carried in `Transition.metadata.configRef` so inspect/
|
|
6
|
+
* diff can attribute platform-injected transitions to the file + path
|
|
7
|
+
* where the user authored them. Always emit an absolute file path; the
|
|
8
|
+
* pointer is a JSON-Pointer-ish hint, intentionally not validated.
|
|
9
|
+
*/
|
|
10
|
+
interface ConfigRef {
|
|
11
|
+
/** Absolute path to the source manifest file. */
|
|
12
|
+
file: string;
|
|
13
|
+
/** Pointer into the manifest, e.g. "Resources/Auth/Properties". */
|
|
14
|
+
pointer: string;
|
|
15
|
+
}
|
|
16
|
+
/**
|
|
17
|
+
* One of the well-known platform contracts that produce extra response
|
|
18
|
+
* transitions. Used as the `cause` token in opaque predicates and as a
|
|
19
|
+
* key for collapsing per-status transitions. Closed enum so the checker
|
|
20
|
+
* and renderers can switch on it.
|
|
21
|
+
*/
|
|
22
|
+
type PlatformCause = "authorization" | "api-key" | "request-validation" | "throttle" | "integration-timeout" | "integration-failure" | "cors-preflight";
|
|
23
|
+
type AuthorizerType = "iam" | "cognito" | "lambda-token" | "lambda-request" | "jwt";
|
|
24
|
+
interface AuthorizerConfig {
|
|
25
|
+
type: AuthorizerType;
|
|
26
|
+
/**
|
|
27
|
+
* When true, missing/invalid credentials produce 401; authenticated
|
|
28
|
+
* but denied produces 403. When false, the authorizer is configured
|
|
29
|
+
* but anonymous calls bypass it (mostly relevant for public-fallback
|
|
30
|
+
* IAM and Lambda authorizers with caching off).
|
|
31
|
+
*/
|
|
32
|
+
identitySourceRequired?: boolean;
|
|
33
|
+
configRef?: ConfigRef;
|
|
34
|
+
}
|
|
35
|
+
interface CorsConfig {
|
|
36
|
+
allowOrigins: string[];
|
|
37
|
+
allowMethods: string[];
|
|
38
|
+
allowHeaders?: string[];
|
|
39
|
+
exposeHeaders?: string[];
|
|
40
|
+
allowCredentials?: boolean;
|
|
41
|
+
maxAge?: number;
|
|
42
|
+
configRef?: ConfigRef;
|
|
43
|
+
}
|
|
44
|
+
interface ThrottleConfig {
|
|
45
|
+
burstLimit?: number;
|
|
46
|
+
rateLimit?: number;
|
|
47
|
+
configRef?: ConfigRef;
|
|
48
|
+
}
|
|
49
|
+
interface RequestValidationConfig {
|
|
50
|
+
body?: boolean;
|
|
51
|
+
params?: boolean;
|
|
52
|
+
headers?: boolean;
|
|
53
|
+
configRef?: ConfigRef;
|
|
54
|
+
}
|
|
55
|
+
/**
|
|
56
|
+
* Pointer from a declared route to the code that implements it. A
|
|
57
|
+
* manifest reader (CFN/SAM, CDK, Terraform) fills this in when it knows
|
|
58
|
+
* which module + export backs the route — e.g. a SAM Lambda proxy
|
|
59
|
+
* integration whose `Handler` names the file and export. The fields are
|
|
60
|
+
* generic "where is the code" identity, not any one manifest's
|
|
61
|
+
* semantics; `aws-apigateway` carries the pointer onto the summary
|
|
62
|
+
* (`metadata.http.implementingHandler`) without interpreting it, so a
|
|
63
|
+
* checker can later correlate the declared route with the extracted
|
|
64
|
+
* handler summary that carries the same REST binding.
|
|
65
|
+
*/
|
|
66
|
+
interface HandlerPointer {
|
|
67
|
+
/** Raw handler reference, e.g. "src/handlers/confirmToken.handler". */
|
|
68
|
+
handler: string;
|
|
69
|
+
/** Module-path portion (before the final dot), e.g. "src/handlers/confirmToken". */
|
|
70
|
+
modulePath: string;
|
|
71
|
+
/** Exported symbol the handler names, e.g. "handler". */
|
|
72
|
+
exportName: string;
|
|
73
|
+
/** Base directory the module path resolves against (SAM CodeUri). */
|
|
74
|
+
codeUri?: string;
|
|
75
|
+
/** Logical id of the function resource that declared the handler. */
|
|
76
|
+
functionLogicalId?: string;
|
|
77
|
+
}
|
|
78
|
+
type IntegrationType = "lambda" | "lambda-proxy" | "http" | "http-proxy" | "mock" | "aws-service" | "vpc-link"
|
|
79
|
+
/**
|
|
80
|
+
* The manifest declared an endpoint but didn't specify the integration
|
|
81
|
+
* type. We can't claim 502/504 will fire without knowing what's behind
|
|
82
|
+
* the route, so platform-failure transitions are suppressed for this
|
|
83
|
+
* type. Used by manifest readers as a fallback rather than fabricating
|
|
84
|
+
* a guessed integration.
|
|
85
|
+
*/
|
|
86
|
+
| "unknown";
|
|
87
|
+
interface IntegrationConfig {
|
|
88
|
+
type: IntegrationType;
|
|
89
|
+
/**
|
|
90
|
+
* Status codes the backend integration can produce. For proxy
|
|
91
|
+
* integrations this is what the handler emits; for non-proxy it's
|
|
92
|
+
* what `IntegrationResponses` map to. Empty array is allowed and
|
|
93
|
+
* means "we don't know" — only platform-injected transitions will
|
|
94
|
+
* be emitted.
|
|
95
|
+
*/
|
|
96
|
+
statusCodes: number[];
|
|
97
|
+
/**
|
|
98
|
+
* REST API Gateway hard cap is 29s; HTTP API is 30s. When set,
|
|
99
|
+
* a synthetic 504 is added if the integration could exceed it.
|
|
100
|
+
* Default behavior: emit 504 unconditionally for lambda/http/aws-service
|
|
101
|
+
* integrations because the timeout *can* fire.
|
|
102
|
+
*/
|
|
103
|
+
timeoutMs?: number;
|
|
104
|
+
configRef?: ConfigRef;
|
|
105
|
+
}
|
|
106
|
+
/** Configuration for a single REST API endpoint (method + path). */
|
|
107
|
+
interface RestEndpointConfig {
|
|
108
|
+
method: string;
|
|
109
|
+
path: string;
|
|
110
|
+
integration: IntegrationConfig;
|
|
111
|
+
/**
|
|
112
|
+
* `null` (or undefined) means no authorizer. To opt out of an
|
|
113
|
+
* inherited API-level default, pass `null` explicitly.
|
|
114
|
+
*/
|
|
115
|
+
authorizer?: AuthorizerConfig | null;
|
|
116
|
+
apiKeyRequired?: boolean;
|
|
117
|
+
requestValidation?: RequestValidationConfig;
|
|
118
|
+
throttle?: ThrottleConfig;
|
|
119
|
+
/**
|
|
120
|
+
* Optional override label for the synthesized handler name. Defaults
|
|
121
|
+
* to `${method.toUpperCase()} ${path}`.
|
|
122
|
+
*/
|
|
123
|
+
name?: string;
|
|
124
|
+
/**
|
|
125
|
+
* Code that implements this endpoint, when the manifest names it
|
|
126
|
+
* (SAM Lambda proxy `Handler`). Emitted as
|
|
127
|
+
* `metadata.http.implementingHandler`; purely additive.
|
|
128
|
+
*/
|
|
129
|
+
implementingHandler?: HandlerPointer;
|
|
130
|
+
configRef?: ConfigRef;
|
|
131
|
+
}
|
|
132
|
+
interface RestApiConfig {
|
|
133
|
+
/** Logical identifier for the API (used in summary identity). */
|
|
134
|
+
id: string;
|
|
135
|
+
/** Recorded as `SourceLocation.file` on each summary. */
|
|
136
|
+
source?: string;
|
|
137
|
+
endpoints: RestEndpointConfig[];
|
|
138
|
+
/** API-level defaults that cascade onto endpoints unless overridden. */
|
|
139
|
+
defaultAuthorizer?: AuthorizerConfig;
|
|
140
|
+
defaultThrottle?: ThrottleConfig;
|
|
141
|
+
/** API-level CORS — produces an OPTIONS endpoint per resource path. */
|
|
142
|
+
cors?: CorsConfig;
|
|
143
|
+
/** Binary media types declared on the API; doesn't affect transitions. */
|
|
144
|
+
binaryMediaTypes?: string[];
|
|
145
|
+
}
|
|
146
|
+
type HttpAuthorizerType = "jwt" | "lambda-request" | "iam";
|
|
147
|
+
interface HttpAuthorizerConfig {
|
|
148
|
+
type: HttpAuthorizerType;
|
|
149
|
+
identitySourceRequired?: boolean;
|
|
150
|
+
configRef?: ConfigRef;
|
|
151
|
+
}
|
|
152
|
+
interface HttpRouteConfig {
|
|
153
|
+
/**
|
|
154
|
+
* Route key in API Gateway's native form: `"<METHOD> <path>"`, or
|
|
155
|
+
* `"$default"` for the catch-all route. The package re-parses this
|
|
156
|
+
* to fill `BoundaryBinding.method` / `path`.
|
|
157
|
+
*/
|
|
158
|
+
routeKey: string;
|
|
159
|
+
integration: IntegrationConfig;
|
|
160
|
+
authorizer?: HttpAuthorizerConfig | null;
|
|
161
|
+
throttle?: ThrottleConfig;
|
|
162
|
+
name?: string;
|
|
163
|
+
/**
|
|
164
|
+
* Code that implements this route, when the manifest names it (SAM
|
|
165
|
+
* Lambda proxy `Handler`). Emitted as
|
|
166
|
+
* `metadata.http.implementingHandler`; purely additive.
|
|
167
|
+
*/
|
|
168
|
+
implementingHandler?: HandlerPointer;
|
|
169
|
+
configRef?: ConfigRef;
|
|
170
|
+
}
|
|
171
|
+
interface HttpApiConfig {
|
|
172
|
+
id: string;
|
|
173
|
+
source?: string;
|
|
174
|
+
routes: HttpRouteConfig[];
|
|
175
|
+
defaultAuthorizer?: HttpAuthorizerConfig;
|
|
176
|
+
defaultThrottle?: ThrottleConfig;
|
|
177
|
+
cors?: CorsConfig;
|
|
178
|
+
}
|
|
179
|
+
|
|
180
|
+
declare function httpApiToSummaries(config: HttpApiConfig): BehavioralSummary[];
|
|
181
|
+
|
|
182
|
+
declare function restApiToSummaries(config: RestApiConfig): BehavioralSummary[];
|
|
183
|
+
|
|
184
|
+
export { type AuthorizerConfig, type AuthorizerType, type ConfigRef, type CorsConfig, type HandlerPointer, type HttpApiConfig, type HttpAuthorizerConfig, type HttpAuthorizerType, type HttpRouteConfig, type IntegrationConfig, type IntegrationType, type PlatformCause, type RequestValidationConfig, type RestApiConfig, type RestEndpointConfig, type ThrottleConfig, httpApiToSummaries, restApiToSummaries };
|
package/dist/index.d.ts
ADDED
|
@@ -0,0 +1,184 @@
|
|
|
1
|
+
import { BehavioralSummary } from '@suss/behavioral-ir';
|
|
2
|
+
|
|
3
|
+
/**
|
|
4
|
+
* Reference back into the source manifest that introduced a piece of
|
|
5
|
+
* configuration. Carried in `Transition.metadata.configRef` so inspect/
|
|
6
|
+
* diff can attribute platform-injected transitions to the file + path
|
|
7
|
+
* where the user authored them. Always emit an absolute file path; the
|
|
8
|
+
* pointer is a JSON-Pointer-ish hint, intentionally not validated.
|
|
9
|
+
*/
|
|
10
|
+
interface ConfigRef {
|
|
11
|
+
/** Absolute path to the source manifest file. */
|
|
12
|
+
file: string;
|
|
13
|
+
/** Pointer into the manifest, e.g. "Resources/Auth/Properties". */
|
|
14
|
+
pointer: string;
|
|
15
|
+
}
|
|
16
|
+
/**
|
|
17
|
+
* One of the well-known platform contracts that produce extra response
|
|
18
|
+
* transitions. Used as the `cause` token in opaque predicates and as a
|
|
19
|
+
* key for collapsing per-status transitions. Closed enum so the checker
|
|
20
|
+
* and renderers can switch on it.
|
|
21
|
+
*/
|
|
22
|
+
type PlatformCause = "authorization" | "api-key" | "request-validation" | "throttle" | "integration-timeout" | "integration-failure" | "cors-preflight";
|
|
23
|
+
type AuthorizerType = "iam" | "cognito" | "lambda-token" | "lambda-request" | "jwt";
|
|
24
|
+
interface AuthorizerConfig {
|
|
25
|
+
type: AuthorizerType;
|
|
26
|
+
/**
|
|
27
|
+
* When true, missing/invalid credentials produce 401; authenticated
|
|
28
|
+
* but denied produces 403. When false, the authorizer is configured
|
|
29
|
+
* but anonymous calls bypass it (mostly relevant for public-fallback
|
|
30
|
+
* IAM and Lambda authorizers with caching off).
|
|
31
|
+
*/
|
|
32
|
+
identitySourceRequired?: boolean;
|
|
33
|
+
configRef?: ConfigRef;
|
|
34
|
+
}
|
|
35
|
+
interface CorsConfig {
|
|
36
|
+
allowOrigins: string[];
|
|
37
|
+
allowMethods: string[];
|
|
38
|
+
allowHeaders?: string[];
|
|
39
|
+
exposeHeaders?: string[];
|
|
40
|
+
allowCredentials?: boolean;
|
|
41
|
+
maxAge?: number;
|
|
42
|
+
configRef?: ConfigRef;
|
|
43
|
+
}
|
|
44
|
+
interface ThrottleConfig {
|
|
45
|
+
burstLimit?: number;
|
|
46
|
+
rateLimit?: number;
|
|
47
|
+
configRef?: ConfigRef;
|
|
48
|
+
}
|
|
49
|
+
interface RequestValidationConfig {
|
|
50
|
+
body?: boolean;
|
|
51
|
+
params?: boolean;
|
|
52
|
+
headers?: boolean;
|
|
53
|
+
configRef?: ConfigRef;
|
|
54
|
+
}
|
|
55
|
+
/**
|
|
56
|
+
* Pointer from a declared route to the code that implements it. A
|
|
57
|
+
* manifest reader (CFN/SAM, CDK, Terraform) fills this in when it knows
|
|
58
|
+
* which module + export backs the route — e.g. a SAM Lambda proxy
|
|
59
|
+
* integration whose `Handler` names the file and export. The fields are
|
|
60
|
+
* generic "where is the code" identity, not any one manifest's
|
|
61
|
+
* semantics; `aws-apigateway` carries the pointer onto the summary
|
|
62
|
+
* (`metadata.http.implementingHandler`) without interpreting it, so a
|
|
63
|
+
* checker can later correlate the declared route with the extracted
|
|
64
|
+
* handler summary that carries the same REST binding.
|
|
65
|
+
*/
|
|
66
|
+
interface HandlerPointer {
|
|
67
|
+
/** Raw handler reference, e.g. "src/handlers/confirmToken.handler". */
|
|
68
|
+
handler: string;
|
|
69
|
+
/** Module-path portion (before the final dot), e.g. "src/handlers/confirmToken". */
|
|
70
|
+
modulePath: string;
|
|
71
|
+
/** Exported symbol the handler names, e.g. "handler". */
|
|
72
|
+
exportName: string;
|
|
73
|
+
/** Base directory the module path resolves against (SAM CodeUri). */
|
|
74
|
+
codeUri?: string;
|
|
75
|
+
/** Logical id of the function resource that declared the handler. */
|
|
76
|
+
functionLogicalId?: string;
|
|
77
|
+
}
|
|
78
|
+
type IntegrationType = "lambda" | "lambda-proxy" | "http" | "http-proxy" | "mock" | "aws-service" | "vpc-link"
|
|
79
|
+
/**
|
|
80
|
+
* The manifest declared an endpoint but didn't specify the integration
|
|
81
|
+
* type. We can't claim 502/504 will fire without knowing what's behind
|
|
82
|
+
* the route, so platform-failure transitions are suppressed for this
|
|
83
|
+
* type. Used by manifest readers as a fallback rather than fabricating
|
|
84
|
+
* a guessed integration.
|
|
85
|
+
*/
|
|
86
|
+
| "unknown";
|
|
87
|
+
interface IntegrationConfig {
|
|
88
|
+
type: IntegrationType;
|
|
89
|
+
/**
|
|
90
|
+
* Status codes the backend integration can produce. For proxy
|
|
91
|
+
* integrations this is what the handler emits; for non-proxy it's
|
|
92
|
+
* what `IntegrationResponses` map to. Empty array is allowed and
|
|
93
|
+
* means "we don't know" — only platform-injected transitions will
|
|
94
|
+
* be emitted.
|
|
95
|
+
*/
|
|
96
|
+
statusCodes: number[];
|
|
97
|
+
/**
|
|
98
|
+
* REST API Gateway hard cap is 29s; HTTP API is 30s. When set,
|
|
99
|
+
* a synthetic 504 is added if the integration could exceed it.
|
|
100
|
+
* Default behavior: emit 504 unconditionally for lambda/http/aws-service
|
|
101
|
+
* integrations because the timeout *can* fire.
|
|
102
|
+
*/
|
|
103
|
+
timeoutMs?: number;
|
|
104
|
+
configRef?: ConfigRef;
|
|
105
|
+
}
|
|
106
|
+
/** Configuration for a single REST API endpoint (method + path). */
|
|
107
|
+
interface RestEndpointConfig {
|
|
108
|
+
method: string;
|
|
109
|
+
path: string;
|
|
110
|
+
integration: IntegrationConfig;
|
|
111
|
+
/**
|
|
112
|
+
* `null` (or undefined) means no authorizer. To opt out of an
|
|
113
|
+
* inherited API-level default, pass `null` explicitly.
|
|
114
|
+
*/
|
|
115
|
+
authorizer?: AuthorizerConfig | null;
|
|
116
|
+
apiKeyRequired?: boolean;
|
|
117
|
+
requestValidation?: RequestValidationConfig;
|
|
118
|
+
throttle?: ThrottleConfig;
|
|
119
|
+
/**
|
|
120
|
+
* Optional override label for the synthesized handler name. Defaults
|
|
121
|
+
* to `${method.toUpperCase()} ${path}`.
|
|
122
|
+
*/
|
|
123
|
+
name?: string;
|
|
124
|
+
/**
|
|
125
|
+
* Code that implements this endpoint, when the manifest names it
|
|
126
|
+
* (SAM Lambda proxy `Handler`). Emitted as
|
|
127
|
+
* `metadata.http.implementingHandler`; purely additive.
|
|
128
|
+
*/
|
|
129
|
+
implementingHandler?: HandlerPointer;
|
|
130
|
+
configRef?: ConfigRef;
|
|
131
|
+
}
|
|
132
|
+
interface RestApiConfig {
|
|
133
|
+
/** Logical identifier for the API (used in summary identity). */
|
|
134
|
+
id: string;
|
|
135
|
+
/** Recorded as `SourceLocation.file` on each summary. */
|
|
136
|
+
source?: string;
|
|
137
|
+
endpoints: RestEndpointConfig[];
|
|
138
|
+
/** API-level defaults that cascade onto endpoints unless overridden. */
|
|
139
|
+
defaultAuthorizer?: AuthorizerConfig;
|
|
140
|
+
defaultThrottle?: ThrottleConfig;
|
|
141
|
+
/** API-level CORS — produces an OPTIONS endpoint per resource path. */
|
|
142
|
+
cors?: CorsConfig;
|
|
143
|
+
/** Binary media types declared on the API; doesn't affect transitions. */
|
|
144
|
+
binaryMediaTypes?: string[];
|
|
145
|
+
}
|
|
146
|
+
type HttpAuthorizerType = "jwt" | "lambda-request" | "iam";
|
|
147
|
+
interface HttpAuthorizerConfig {
|
|
148
|
+
type: HttpAuthorizerType;
|
|
149
|
+
identitySourceRequired?: boolean;
|
|
150
|
+
configRef?: ConfigRef;
|
|
151
|
+
}
|
|
152
|
+
interface HttpRouteConfig {
|
|
153
|
+
/**
|
|
154
|
+
* Route key in API Gateway's native form: `"<METHOD> <path>"`, or
|
|
155
|
+
* `"$default"` for the catch-all route. The package re-parses this
|
|
156
|
+
* to fill `BoundaryBinding.method` / `path`.
|
|
157
|
+
*/
|
|
158
|
+
routeKey: string;
|
|
159
|
+
integration: IntegrationConfig;
|
|
160
|
+
authorizer?: HttpAuthorizerConfig | null;
|
|
161
|
+
throttle?: ThrottleConfig;
|
|
162
|
+
name?: string;
|
|
163
|
+
/**
|
|
164
|
+
* Code that implements this route, when the manifest names it (SAM
|
|
165
|
+
* Lambda proxy `Handler`). Emitted as
|
|
166
|
+
* `metadata.http.implementingHandler`; purely additive.
|
|
167
|
+
*/
|
|
168
|
+
implementingHandler?: HandlerPointer;
|
|
169
|
+
configRef?: ConfigRef;
|
|
170
|
+
}
|
|
171
|
+
interface HttpApiConfig {
|
|
172
|
+
id: string;
|
|
173
|
+
source?: string;
|
|
174
|
+
routes: HttpRouteConfig[];
|
|
175
|
+
defaultAuthorizer?: HttpAuthorizerConfig;
|
|
176
|
+
defaultThrottle?: ThrottleConfig;
|
|
177
|
+
cors?: CorsConfig;
|
|
178
|
+
}
|
|
179
|
+
|
|
180
|
+
declare function httpApiToSummaries(config: HttpApiConfig): BehavioralSummary[];
|
|
181
|
+
|
|
182
|
+
declare function restApiToSummaries(config: RestApiConfig): BehavioralSummary[];
|
|
183
|
+
|
|
184
|
+
export { type AuthorizerConfig, type AuthorizerType, type ConfigRef, type CorsConfig, type HandlerPointer, type HttpApiConfig, type HttpAuthorizerConfig, type HttpAuthorizerType, type HttpRouteConfig, type IntegrationConfig, type IntegrationType, type PlatformCause, type RequestValidationConfig, type RestApiConfig, type RestEndpointConfig, type ThrottleConfig, httpApiToSummaries, restApiToSummaries };
|