From b73ebff021a6a963d819fefd7f50eb7a5bcac6c9 Mon Sep 17 00:00:00 2001 From: awstools Date: Thu, 25 Apr 2024 18:15:39 +0000 Subject: [PATCH] feat(client-sfn): Add new ValidateStateMachineDefinition operation, which performs syntax checking on the definition of a Amazon States Language (ASL) state machine. --- clients/client-sfn/README.md | 8 + clients/client-sfn/src/SFN.ts | 23 +++ clients/client-sfn/src/SFNClient.ts | 10 +- .../src/commands/RedriveExecutionCommand.ts | 3 + .../ValidateStateMachineDefinitionCommand.ts | 122 +++++++++++++++ clients/client-sfn/src/commands/index.ts | 1 + clients/client-sfn/src/models/models_0.ts | 110 +++++++++++++ .../client-sfn/src/protocols/Aws_json1_0.ts | 46 ++++++ codegen/sdk-codegen/aws-models/sfn.json | 144 ++++++++++++++++++ 9 files changed, 465 insertions(+), 2 deletions(-) create mode 100644 clients/client-sfn/src/commands/ValidateStateMachineDefinitionCommand.ts diff --git a/clients/client-sfn/README.md b/clients/client-sfn/README.md index 524a4e252382..7b624853b2e6 100644 --- a/clients/client-sfn/README.md +++ b/clients/client-sfn/README.md @@ -510,3 +510,11 @@ UpdateStateMachineAlias [Command API Reference](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/client/sfn/command/UpdateStateMachineAliasCommand/) / [Input](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/Package/-aws-sdk-client-sfn/Interface/UpdateStateMachineAliasCommandInput/) / [Output](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/Package/-aws-sdk-client-sfn/Interface/UpdateStateMachineAliasCommandOutput/) +
+ +ValidateStateMachineDefinition + + +[Command API Reference](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/client/sfn/command/ValidateStateMachineDefinitionCommand/) / [Input](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/Package/-aws-sdk-client-sfn/Interface/ValidateStateMachineDefinitionCommandInput/) / [Output](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/Package/-aws-sdk-client-sfn/Interface/ValidateStateMachineDefinitionCommandOutput/) + +
diff --git a/clients/client-sfn/src/SFN.ts b/clients/client-sfn/src/SFN.ts index 60fc0f750612..42d5c3d9d870 100644 --- a/clients/client-sfn/src/SFN.ts +++ b/clients/client-sfn/src/SFN.ts @@ -170,6 +170,11 @@ import { UpdateStateMachineCommandInput, UpdateStateMachineCommandOutput, } from "./commands/UpdateStateMachineCommand"; +import { + ValidateStateMachineDefinitionCommand, + ValidateStateMachineDefinitionCommandInput, + ValidateStateMachineDefinitionCommandOutput, +} from "./commands/ValidateStateMachineDefinitionCommand"; import { SFNClient, SFNClientConfig } from "./SFNClient"; const commands = { @@ -209,6 +214,7 @@ const commands = { UpdateMapRunCommand, UpdateStateMachineCommand, UpdateStateMachineAliasCommand, + ValidateStateMachineDefinitionCommand, }; export interface SFN { @@ -763,6 +769,23 @@ export interface SFN { options: __HttpHandlerOptions, cb: (err: any, data?: UpdateStateMachineAliasCommandOutput) => void ): void; + + /** + * @see {@link ValidateStateMachineDefinitionCommand} + */ + validateStateMachineDefinition( + args: ValidateStateMachineDefinitionCommandInput, + options?: __HttpHandlerOptions + ): Promise; + validateStateMachineDefinition( + args: ValidateStateMachineDefinitionCommandInput, + cb: (err: any, data?: ValidateStateMachineDefinitionCommandOutput) => void + ): void; + validateStateMachineDefinition( + args: ValidateStateMachineDefinitionCommandInput, + options: __HttpHandlerOptions, + cb: (err: any, data?: ValidateStateMachineDefinitionCommandOutput) => void + ): void; } /** diff --git a/clients/client-sfn/src/SFNClient.ts b/clients/client-sfn/src/SFNClient.ts index a87f163b537e..3d4579c115df 100644 --- a/clients/client-sfn/src/SFNClient.ts +++ b/clients/client-sfn/src/SFNClient.ts @@ -125,6 +125,10 @@ import { UpdateStateMachineAliasCommandOutput, } from "./commands/UpdateStateMachineAliasCommand"; import { UpdateStateMachineCommandInput, UpdateStateMachineCommandOutput } from "./commands/UpdateStateMachineCommand"; +import { + ValidateStateMachineDefinitionCommandInput, + ValidateStateMachineDefinitionCommandOutput, +} from "./commands/ValidateStateMachineDefinitionCommand"; import { ClientInputEndpointParameters, ClientResolvedEndpointParameters, @@ -175,7 +179,8 @@ export type ServiceInputTypes = | UntagResourceCommandInput | UpdateMapRunCommandInput | UpdateStateMachineAliasCommandInput - | UpdateStateMachineCommandInput; + | UpdateStateMachineCommandInput + | ValidateStateMachineDefinitionCommandInput; /** * @public @@ -216,7 +221,8 @@ export type ServiceOutputTypes = | UntagResourceCommandOutput | UpdateMapRunCommandOutput | UpdateStateMachineAliasCommandOutput - | UpdateStateMachineCommandOutput; + | UpdateStateMachineCommandOutput + | ValidateStateMachineDefinitionCommandOutput; /** * @public diff --git a/clients/client-sfn/src/commands/RedriveExecutionCommand.ts b/clients/client-sfn/src/commands/RedriveExecutionCommand.ts index 14e8c581ce1f..80e46c919057 100644 --- a/clients/client-sfn/src/commands/RedriveExecutionCommand.ts +++ b/clients/client-sfn/src/commands/RedriveExecutionCommand.ts @@ -86,6 +86,9 @@ export interface RedriveExecutionCommandOutput extends RedriveExecutionOutput, _ * @throws {@link InvalidArn} (client fault) *

The provided Amazon Resource Name (ARN) is not valid.

* + * @throws {@link ValidationException} (client fault) + *

The input does not satisfy the constraints specified by an Amazon Web Services service.

+ * * @throws {@link SFNServiceException} *

Base exception class for all service exceptions from SFN service.

* diff --git a/clients/client-sfn/src/commands/ValidateStateMachineDefinitionCommand.ts b/clients/client-sfn/src/commands/ValidateStateMachineDefinitionCommand.ts new file mode 100644 index 000000000000..7ab30297ef56 --- /dev/null +++ b/clients/client-sfn/src/commands/ValidateStateMachineDefinitionCommand.ts @@ -0,0 +1,122 @@ +// smithy-typescript generated code +import { getEndpointPlugin } from "@smithy/middleware-endpoint"; +import { getSerdePlugin } from "@smithy/middleware-serde"; +import { Command as $Command } from "@smithy/smithy-client"; +import { MetadataBearer as __MetadataBearer } from "@smithy/types"; + +import { commonParams } from "../endpoint/EndpointParameters"; +import { + ValidateStateMachineDefinitionInput, + ValidateStateMachineDefinitionInputFilterSensitiveLog, + ValidateStateMachineDefinitionOutput, +} from "../models/models_0"; +import { + de_ValidateStateMachineDefinitionCommand, + se_ValidateStateMachineDefinitionCommand, +} from "../protocols/Aws_json1_0"; +import { ServiceInputTypes, ServiceOutputTypes, SFNClientResolvedConfig } from "../SFNClient"; + +/** + * @public + */ +export { __MetadataBearer, $Command }; +/** + * @public + * + * The input for {@link ValidateStateMachineDefinitionCommand}. + */ +export interface ValidateStateMachineDefinitionCommandInput extends ValidateStateMachineDefinitionInput {} +/** + * @public + * + * The output of {@link ValidateStateMachineDefinitionCommand}. + */ +export interface ValidateStateMachineDefinitionCommandOutput + extends ValidateStateMachineDefinitionOutput, + __MetadataBearer {} + +/** + *

Validates the syntax of a state machine definition.

+ *

You can validate that a state machine definition is correct without + * creating a state machine resource. Step Functions will implicitly perform the same + * syntax check when you invoke CreateStateMachine and + * UpdateStateMachine. State machine definitions are specified using a + * JSON-based, structured language. For more information on Amazon States Language see Amazon States Language (ASL).

+ *

Suggested uses for ValidateStateMachineDefinition:

+ * + * + *

Errors found in the state machine definition will be returned in the response as a list of diagnostic elements, rather than raise an exception.

+ * + * @example + * Use a bare-bones client and the command you need to make an API call. + * ```javascript + * import { SFNClient, ValidateStateMachineDefinitionCommand } from "@aws-sdk/client-sfn"; // ES Modules import + * // const { SFNClient, ValidateStateMachineDefinitionCommand } = require("@aws-sdk/client-sfn"); // CommonJS import + * const client = new SFNClient(config); + * const input = { // ValidateStateMachineDefinitionInput + * definition: "STRING_VALUE", // required + * type: "STANDARD" || "EXPRESS", + * }; + * const command = new ValidateStateMachineDefinitionCommand(input); + * const response = await client.send(command); + * // { // ValidateStateMachineDefinitionOutput + * // result: "OK" || "FAIL", // required + * // diagnostics: [ // ValidateStateMachineDefinitionDiagnosticList // required + * // { // ValidateStateMachineDefinitionDiagnostic + * // severity: "ERROR", // required + * // code: "STRING_VALUE", // required + * // message: "STRING_VALUE", // required + * // location: "STRING_VALUE", + * // }, + * // ], + * // }; + * + * ``` + * + * @param ValidateStateMachineDefinitionCommandInput - {@link ValidateStateMachineDefinitionCommandInput} + * @returns {@link ValidateStateMachineDefinitionCommandOutput} + * @see {@link ValidateStateMachineDefinitionCommandInput} for command's `input` shape. + * @see {@link ValidateStateMachineDefinitionCommandOutput} for command's `response` shape. + * @see {@link SFNClientResolvedConfig | config} for SFNClient's `config` shape. + * + * @throws {@link ValidationException} (client fault) + *

The input does not satisfy the constraints specified by an Amazon Web Services service.

+ * + * @throws {@link SFNServiceException} + *

Base exception class for all service exceptions from SFN service.

+ * + * @public + */ +export class ValidateStateMachineDefinitionCommand extends $Command + .classBuilder< + ValidateStateMachineDefinitionCommandInput, + ValidateStateMachineDefinitionCommandOutput, + SFNClientResolvedConfig, + ServiceInputTypes, + ServiceOutputTypes + >() + .ep({ + ...commonParams, + }) + .m(function (this: any, Command: any, cs: any, config: SFNClientResolvedConfig, o: any) { + return [ + getSerdePlugin(config, this.serialize, this.deserialize), + getEndpointPlugin(config, Command.getEndpointParameterInstructions()), + ]; + }) + .s("AWSStepFunctions", "ValidateStateMachineDefinition", {}) + .n("SFNClient", "ValidateStateMachineDefinitionCommand") + .f(ValidateStateMachineDefinitionInputFilterSensitiveLog, void 0) + .ser(se_ValidateStateMachineDefinitionCommand) + .de(de_ValidateStateMachineDefinitionCommand) + .build() {} diff --git a/clients/client-sfn/src/commands/index.ts b/clients/client-sfn/src/commands/index.ts index d12cecf9a4c5..a981622013c9 100644 --- a/clients/client-sfn/src/commands/index.ts +++ b/clients/client-sfn/src/commands/index.ts @@ -35,3 +35,4 @@ export * from "./UntagResourceCommand"; export * from "./UpdateMapRunCommand"; export * from "./UpdateStateMachineAliasCommand"; export * from "./UpdateStateMachineCommand"; +export * from "./ValidateStateMachineDefinitionCommand"; diff --git a/clients/client-sfn/src/models/models_0.ts b/clients/client-sfn/src/models/models_0.ts index 5443a50ade29..e17c61f3625c 100644 --- a/clients/client-sfn/src/models/models_0.ts +++ b/clients/client-sfn/src/models/models_0.ts @@ -4548,6 +4548,106 @@ export interface UpdateStateMachineAliasOutput { updateDate: Date | undefined; } +/** + * @public + */ +export interface ValidateStateMachineDefinitionInput { + /** + *

The Amazon States Language definition of the state machine. For more information, see + * Amazon States Language (ASL).

+ * @public + */ + definition: string | undefined; + + /** + *

The target type of state machine for this definition. The default is STANDARD.

+ * @public + */ + type?: StateMachineType; +} + +/** + * @public + * @enum + */ +export const ValidateStateMachineDefinitionSeverity = { + ERROR: "ERROR", +} as const; + +/** + * @public + */ +export type ValidateStateMachineDefinitionSeverity = + (typeof ValidateStateMachineDefinitionSeverity)[keyof typeof ValidateStateMachineDefinitionSeverity]; + +/** + *

Describes an error found during validation. Validation errors found in the definition + * return in the response as diagnostic elements, rather + * than raise an exception.

+ * @public + */ +export interface ValidateStateMachineDefinitionDiagnostic { + /** + *

A value of ERROR means that you cannot create or update a state machine with this definition.

+ * @public + */ + severity: ValidateStateMachineDefinitionSeverity | undefined; + + /** + *

Identifying code for the diagnostic.

+ * @public + */ + code: string | undefined; + + /** + *

Message describing the diagnostic condition.

+ * @public + */ + message: string | undefined; + + /** + *

Location of the issue in the state machine, if available.

+ *

For errors specific to a field, the location could be in the format: /States//, for example: /States/FailState/ErrorPath.

+ * @public + */ + location?: string; +} + +/** + * @public + * @enum + */ +export const ValidateStateMachineDefinitionResultCode = { + FAIL: "FAIL", + OK: "OK", +} as const; + +/** + * @public + */ +export type ValidateStateMachineDefinitionResultCode = + (typeof ValidateStateMachineDefinitionResultCode)[keyof typeof ValidateStateMachineDefinitionResultCode]; + +/** + * @public + */ +export interface ValidateStateMachineDefinitionOutput { + /** + *

The result value will be OK when no syntax errors are found, or + * FAIL if the workflow definition does not pass verification.

+ * @public + */ + result: ValidateStateMachineDefinitionResultCode | undefined; + + /** + *

If the result is OK, this field will be empty. When there are errors, + * this field will contain an array of Diagnostic objects + * to help you troubleshoot.

+ * @public + */ + diagnostics: ValidateStateMachineDefinitionDiagnostic[] | undefined; +} + /** * @internal */ @@ -5062,3 +5162,13 @@ export const UpdateStateMachineAliasInputFilterSensitiveLog = (obj: UpdateStateM ...obj, ...(obj.description && { description: SENSITIVE_STRING }), }); + +/** + * @internal + */ +export const ValidateStateMachineDefinitionInputFilterSensitiveLog = ( + obj: ValidateStateMachineDefinitionInput +): any => ({ + ...obj, + ...(obj.definition && { definition: SENSITIVE_STRING }), +}); diff --git a/clients/client-sfn/src/protocols/Aws_json1_0.ts b/clients/client-sfn/src/protocols/Aws_json1_0.ts index 9b1eba1d39a0..8dc44bf233e6 100644 --- a/clients/client-sfn/src/protocols/Aws_json1_0.ts +++ b/clients/client-sfn/src/protocols/Aws_json1_0.ts @@ -100,6 +100,10 @@ import { UpdateStateMachineAliasCommandOutput, } from "../commands/UpdateStateMachineAliasCommand"; import { UpdateStateMachineCommandInput, UpdateStateMachineCommandOutput } from "../commands/UpdateStateMachineCommand"; +import { + ValidateStateMachineDefinitionCommandInput, + ValidateStateMachineDefinitionCommandOutput, +} from "../commands/ValidateStateMachineDefinitionCommand"; import { ActivityDoesNotExist, ActivityLimitExceeded, @@ -200,6 +204,7 @@ import { UpdateStateMachineAliasOutput, UpdateStateMachineInput, UpdateStateMachineOutput, + ValidateStateMachineDefinitionInput, ValidationException, } from "../models/models_0"; import { SFNServiceException as __BaseException } from "../models/SFNServiceException"; @@ -686,6 +691,19 @@ export const se_UpdateStateMachineAliasCommand = async ( return buildHttpRpcRequest(context, headers, "/", undefined, body); }; +/** + * serializeAws_json1_0ValidateStateMachineDefinitionCommand + */ +export const se_ValidateStateMachineDefinitionCommand = async ( + input: ValidateStateMachineDefinitionCommandInput, + context: __SerdeContext +): Promise<__HttpRequest> => { + const headers: __HeaderBag = sharedHeaders("ValidateStateMachineDefinition"); + let body: any; + body = JSON.stringify(_json(input)); + return buildHttpRpcRequest(context, headers, "/", undefined, body); +}; + /** * deserializeAws_json1_0CreateActivityCommand */ @@ -1406,6 +1424,26 @@ export const de_UpdateStateMachineAliasCommand = async ( return response; }; +/** + * deserializeAws_json1_0ValidateStateMachineDefinitionCommand + */ +export const de_ValidateStateMachineDefinitionCommand = async ( + output: __HttpResponse, + context: __SerdeContext +): Promise => { + if (output.statusCode >= 300) { + return de_CommandError(output, context); + } + const data: any = await parseBody(output.body, context); + let contents: any = {}; + contents = _json(data); + const response: ValidateStateMachineDefinitionCommandOutput = { + $metadata: deserializeMetadata(output), + ...contents, + }; + return response; +}; + /** * deserialize_Aws_json1_0CommandError */ @@ -2035,6 +2073,8 @@ const se_UpdateMapRunInput = (input: UpdateMapRunInput, context: __SerdeContext) // se_UpdateStateMachineInput omitted. +// se_ValidateStateMachineDefinitionInput omitted. + // de_ActivityDoesNotExist omitted. // de_ActivityFailedEventDetails omitted. @@ -2723,6 +2763,12 @@ const de_UpdateStateMachineOutput = (output: any, context: __SerdeContext): Upda }) as any; }; +// de_ValidateStateMachineDefinitionDiagnostic omitted. + +// de_ValidateStateMachineDefinitionDiagnosticList omitted. + +// de_ValidateStateMachineDefinitionOutput omitted. + // de_ValidationException omitted. const deserializeMetadata = (output: __HttpResponse): __ResponseMetadata => ({ diff --git a/codegen/sdk-codegen/aws-models/sfn.json b/codegen/sdk-codegen/aws-models/sfn.json index 067b2fdd3dbe..ad2942fa9014 100644 --- a/codegen/sdk-codegen/aws-models/sfn.json +++ b/codegen/sdk-codegen/aws-models/sfn.json @@ -140,6 +140,9 @@ }, { "target": "com.amazonaws.sfn#UpdateStateMachineAlias" + }, + { + "target": "com.amazonaws.sfn#ValidateStateMachineDefinition" } ], "traits": { @@ -5304,6 +5307,9 @@ }, { "target": "com.amazonaws.sfn#InvalidArn" + }, + { + "target": "com.amazonaws.sfn#ValidationException" } ], "traits": { @@ -7193,6 +7199,144 @@ "smithy.api#output": {} } }, + "com.amazonaws.sfn#ValidateStateMachineDefinition": { + "type": "operation", + "input": { + "target": "com.amazonaws.sfn#ValidateStateMachineDefinitionInput" + }, + "output": { + "target": "com.amazonaws.sfn#ValidateStateMachineDefinitionOutput" + }, + "errors": [ + { + "target": "com.amazonaws.sfn#ValidationException" + } + ], + "traits": { + "smithy.api#documentation": "

Validates the syntax of a state machine definition.

\n

You can validate that a state machine definition is correct without \n creating a state machine resource. Step Functions will implicitly perform the same\n syntax check when you invoke CreateStateMachine and\n UpdateStateMachine. State machine definitions are specified using a\n JSON-based, structured language. For more information on Amazon States Language see Amazon States Language (ASL).

\n

Suggested uses for ValidateStateMachineDefinition:

\n
    \n
  • \n

    Integrate automated checks into your code review or Continuous Integration\n (CI) process to validate state machine definitions before starting\n deployments.

    \n
    • \n
  • \n

    Run the validation from a Git pre-commit hook to check your state machine\n definitions before committing them to your source repository.

    \n
    • \n
\n \n

Errors found in the state machine definition will be returned in the response as a list of diagnostic elements, rather than raise an exception.

\n " + } + }, + "com.amazonaws.sfn#ValidateStateMachineDefinitionCode": { + "type": "string" + }, + "com.amazonaws.sfn#ValidateStateMachineDefinitionDiagnostic": { + "type": "structure", + "members": { + "severity": { + "target": "com.amazonaws.sfn#ValidateStateMachineDefinitionSeverity", + "traits": { + "smithy.api#documentation": "

A value of ERROR means that you cannot create or update a state machine with this definition.

", + "smithy.api#required": {} + } + }, + "code": { + "target": "com.amazonaws.sfn#ValidateStateMachineDefinitionCode", + "traits": { + "smithy.api#documentation": "

Identifying code for the diagnostic.

", + "smithy.api#required": {} + } + }, + "message": { + "target": "com.amazonaws.sfn#ValidateStateMachineDefinitionMessage", + "traits": { + "smithy.api#documentation": "

Message describing the diagnostic condition.

", + "smithy.api#required": {} + } + }, + "location": { + "target": "com.amazonaws.sfn#ValidateStateMachineDefinitionLocation", + "traits": { + "smithy.api#documentation": "

Location of the issue in the state machine, if available.

\n

For errors specific to a field, the location could be in the format: /States//, for example: /States/FailState/ErrorPath.

" + } + } + }, + "traits": { + "smithy.api#documentation": "

Describes an error found during validation. Validation errors found in the definition\n return in the response as diagnostic elements, rather\n than raise an exception.

" + } + }, + "com.amazonaws.sfn#ValidateStateMachineDefinitionDiagnosticList": { + "type": "list", + "member": { + "target": "com.amazonaws.sfn#ValidateStateMachineDefinitionDiagnostic" + } + }, + "com.amazonaws.sfn#ValidateStateMachineDefinitionInput": { + "type": "structure", + "members": { + "definition": { + "target": "com.amazonaws.sfn#Definition", + "traits": { + "smithy.api#documentation": "

The Amazon States Language definition of the state machine. For more information, see\n Amazon States Language (ASL).

", + "smithy.api#required": {} + } + }, + "type": { + "target": "com.amazonaws.sfn#StateMachineType", + "traits": { + "smithy.api#documentation": "

The target type of state machine for this definition. The default is STANDARD.

" + } + } + }, + "traits": { + "smithy.api#input": {} + } + }, + "com.amazonaws.sfn#ValidateStateMachineDefinitionLocation": { + "type": "string" + }, + "com.amazonaws.sfn#ValidateStateMachineDefinitionMessage": { + "type": "string" + }, + "com.amazonaws.sfn#ValidateStateMachineDefinitionOutput": { + "type": "structure", + "members": { + "result": { + "target": "com.amazonaws.sfn#ValidateStateMachineDefinitionResultCode", + "traits": { + "smithy.api#documentation": "

The result value will be OK when no syntax errors are found, or\n FAIL if the workflow definition does not pass verification.

", + "smithy.api#required": {} + } + }, + "diagnostics": { + "target": "com.amazonaws.sfn#ValidateStateMachineDefinitionDiagnosticList", + "traits": { + "smithy.api#documentation": "

If the result is OK, this field will be empty. When there are errors,\n this field will contain an array of Diagnostic objects\n to help you troubleshoot.

", + "smithy.api#required": {} + } + } + }, + "traits": { + "smithy.api#output": {} + } + }, + "com.amazonaws.sfn#ValidateStateMachineDefinitionResultCode": { + "type": "enum", + "members": { + "OK": { + "target": "smithy.api#Unit", + "traits": { + "smithy.api#enumValue": "OK" + } + }, + "FAIL": { + "target": "smithy.api#Unit", + "traits": { + "smithy.api#enumValue": "FAIL" + } + } + } + }, + "com.amazonaws.sfn#ValidateStateMachineDefinitionSeverity": { + "type": "enum", + "members": { + "ERROR": { + "target": "smithy.api#Unit", + "traits": { + "smithy.api#enumValue": "ERROR" + } + } + } + }, "com.amazonaws.sfn#ValidationException": { "type": "structure", "members": {