feat(client-sfn): Add new ValidateStateMachineDefinition operation, which performs syntax checking on the definition of a Amazon States Language (ASL) state machine.

awstools · awstools · commit b73ebff021a6 · 2024-04-25T18:15:39.000Z
diff --git 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/)
 
 </details>
+<details>
+<summary>
+ValidateStateMachineDefinition
+</summary>
+
+[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/)
+
+</details>
diff --git 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<ValidateStateMachineDefinitionCommandOutput>;
+  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
@@ -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
@@ -86,6 +86,9 @@ export interface RedriveExecutionCommandOutput extends RedriveExecutionOutput, _
  * @throws {@link InvalidArn} (client fault)
  *  <p>The provided Amazon Resource Name (ARN) is not valid.</p>
  *
+ * @throws {@link ValidationException} (client fault)
+ *  <p>The input does not satisfy the constraints specified by an Amazon Web Services service.</p>
+ *
  * @throws {@link SFNServiceException}
  * <p>Base exception class for all service exceptions from SFN service.</p>
  *
diff --git a/clients/client-sfn/src/commands/ValidateStateMachineDefinitionCommand.ts 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 {}
+
+/**
+ * <p>Validates the syntax of a state machine definition.</p>
+ *          <p>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 <code>CreateStateMachine</code> and
+ *                 <code>UpdateStateMachine</code>. State machine definitions are specified using a
+ *             JSON-based, structured language. For more information on Amazon States Language see <a href="https://docs.aws.amazon.com/step-functions/latest/dg/concepts-amazon-states-language.html">Amazon States Language</a> (ASL). </p>
+ *          <p>Suggested uses for <code>ValidateStateMachineDefinition</code>:</p>
+ *          <ul>
+ *             <li>
+ *                <p>Integrate automated checks into your code review or Continuous Integration
+ *                     (CI) process to validate state machine definitions before starting
+ *                     deployments.</p>
+ *             </li>
+ *             <li>
+ *                <p>Run the validation from a Git pre-commit hook to check your state machine
+ *                     definitions before committing them to your source repository.</p>
+ *             </li>
+ *          </ul>
+ *          <note>
+ *             <p>Errors found in the state machine definition will be returned in the response as a list of <b>diagnostic elements</b>, rather than raise an exception.</p>
+ *          </note>
+ * @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)
+ *  <p>The input does not satisfy the constraints specified by an Amazon Web Services service.</p>
+ *
+ * @throws {@link SFNServiceException}
+ * <p>Base exception class for all service exceptions from SFN service.</p>
+ *
+ * @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
@@ -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
@@ -4548,6 +4548,106 @@ export interface UpdateStateMachineAliasOutput {
   updateDate: Date | undefined;
 }
 
+/**
+ * @public
+ */
+export interface ValidateStateMachineDefinitionInput {
+  /**
+   * <p>The Amazon States Language definition of the state machine. For more information, see
+   *             <a href="https://docs.aws.amazon.com/step-functions/latest/dg/concepts-amazon-states-language.html">Amazon States Language</a> (ASL).</p>
+   * @public
+   */
+  definition: string | undefined;
+
+  /**
+   * <p>The target type of state machine for this definition. The default is <code>STANDARD</code>.</p>
+   * @public
+   */
+  type?: StateMachineType;
+}
+
+/**
+ * @public
+ * @enum
+ */
+export const ValidateStateMachineDefinitionSeverity = {
+  ERROR: "ERROR",
+} as const;
+
+/**
+ * @public
+ */
+export type ValidateStateMachineDefinitionSeverity =
+  (typeof ValidateStateMachineDefinitionSeverity)[keyof typeof ValidateStateMachineDefinitionSeverity];
+
+/**
+ * <p>Describes an error found during validation. Validation errors found in the definition
+ *             return in the response as <b>diagnostic elements</b>, rather
+ *             than raise an exception.</p>
+ * @public
+ */
+export interface ValidateStateMachineDefinitionDiagnostic {
+  /**
+   * <p>A value of <code>ERROR</code> means that you cannot create or update a state machine with this definition.</p>
+   * @public
+   */
+  severity: ValidateStateMachineDefinitionSeverity | undefined;
+
+  /**
+   * <p>Identifying code for the diagnostic.</p>
+   * @public
+   */
+  code: string | undefined;
+
+  /**
+   * <p>Message describing the diagnostic condition.</p>
+   * @public
+   */
+  message: string | undefined;
+
+  /**
+   * <p>Location of the issue in the state machine, if available.</p>
+   *          <p>For errors specific to a field, the location could be in the format: <code>/States/<StateName>/<FieldName></code>, for example: <code>/States/FailState/ErrorPath</code>.</p>
+   * @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 {
+  /**
+   * <p>The result value will be <code>OK</code> when no syntax errors are found, or
+   *                 <code>FAIL</code> if the workflow definition does not pass verification.</p>
+   * @public
+   */
+  result: ValidateStateMachineDefinitionResultCode | undefined;
+
+  /**
+   * <p>If the result is <code>OK</code>, this field will be empty. When there are errors,
+   *             this field will contain an array of <b>Diagnostic</b> objects
+   *             to help you troubleshoot.</p>
+   * @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
diff --git a/codegen/sdk-codegen/aws-models/sfn.json b/codegen/sdk-codegen/aws-models/sfn.json

Original file line number	Diff line number	Diff line change
`@@ -86,6 +86,9 @@ export interface RedriveExecutionCommandOutput extends RedriveExecutionOutput, _`
`86`	`86`	`* @throws {@link InvalidArn} (client fault)`
`87`	`87`	`* <p>The provided Amazon Resource Name (ARN) is not valid.</p>`
`88`	`88`	`*`
	`89`	`+ * @throws {@link ValidationException} (client fault)`
	`90`	`+ * <p>The input does not satisfy the constraints specified by an Amazon Web Services service.</p>`
	`91`	`+ *`
`89`	`92`	`* @throws {@link SFNServiceException}`
`90`	`93`	`* <p>Base exception class for all service exceptions from SFN service.</p>`
`91`	`94`	`*`