Merge pull request #89 from nibble-4bits/feature/retry-override-cli-option

Feature/retry override cli option

Author: nibble-4bits

README.md

@@ -41,6 +41,7 @@ This package lets you run AWS Step Functions state machines completely locally,
   - [Overriding Task and Wait states](#overriding-task-and-wait-states)
     - [Task state override](#task-state-override)
     - [Wait state override](#wait-state-override)
+    - [Retry field pause override](#retry-field-pause-override)
   - [Passing a custom Context Object](#passing-a-custom-context-object)
   - [Disabling ASL validations](#disabling-asl-validations)
   - [Exit codes](#exit-codes)
@@ -362,6 +363,54 @@ local-sfn \
 
 This command would execute the state machine, and override `Wait` states `WaitResponse` and `PauseUntilSignal` to pause the execution for 1500 and 250 milliseconds, respectively. The `Delay` state wouldn't be paused at all, since the override value is set to 0.
 
+#### Retry field pause override
+
+To override the duration of the pause in the `Retry` field of a state, pass the `-r, --override-retry` option. This option takes as value the name of the state whose `Retry` field you want to override, and a number that represents the amount in milliseconds that you want to pause the execution for before retrying the state. The state name and the milliseconds amount must be separated by a colon `:`.
+
+For example, suppose the state machine definition contains a state called `TaskToRetry` that is defined as follows:
+
+```json
+{
+  "Type": "Task",
+  "Resource": "arn:aws:lambda:us-east-1:123456789012:function:HelloWorld",
+  "Retry": [
+    { "ErrorEquals": ["States.Timeout", "SyntaxError"] },
+    { "ErrorEquals": ["RangeError"] },
+    { "ErrorEquals": ["States.ALL"] }
+  ],
+  "End": true
+}
+```
+
+Then, the following command is run:
+
+```sh
+local-sfn -f state-machine.json -r TaskToRetry:100 '{ "num1": 1, "num2": 2 }'
+```
+
+This command would execute the state machine, and if the `TaskToRetry` state fails, the execution would be paused for 100 milliseconds before retrying the state again, disregarding the `IntervalSeconds`, `BackoffRate`, `MaxDelaySeconds`, and `JitterStrategy` fields that could've been specified in any of the `Retry` field retriers.
+
+Alternatively, you can also pass a list of comma-separated numbers as value, to override the duration of specific retriers, for instance:
+
+```sh
+local-sfn -f state-machine.json -r TaskToRetry:100,-1,20 '{ "num1": 1, "num2": 2 }'
+```
+
+The above command would pause the execution for 100 milliseconds if the state error is matched by the first retrier and it would pause for 20 milliseconds if the error matches the third retrier. Note that a -1 was passed for the second retrier. This means that the pause duration of the second retrier will not be overridden, instead, it will be calculated as usually with the `IntervalSeconds` and the other retrier fields, or use the default values if said fields are not specified.
+
+Furthermore, you can pass this option multiple times, to override the `Retry` fields in multiple states. For example:
+
+```sh
+local-sfn \
+  -f state-machine.json \
+  -r SendRequest:1500 \
+  -r ProcessData:250 \
+  -r MapResponses:0 \
+  '{ "num1": 1, "num2": 2 }'
+```
+
+This command would execute the state machine, and override the duration of the retry pause in states `SendRequest` and `ProcessData` to pause the execution for 1500 and 250 milliseconds, respectively. The retry in the `MapResponses` state wouldn't be paused at all, since the override value is set to 0.
+
 ### Passing a custom Context Object
 
 If the JSONPaths in your definition reference the Context Object, you can provide a mock Context Object by passing either the `--context` or the `--context-file` option. For example, given the following definition:

__tests__/cli/CLI.test.ts

@@ -34,7 +34,7 @@ describe('CLI', () => {
 
       await expect(program.parseAsync([], { from: 'user' })).rejects.toThrow();
       expect(helpStr).toBe(
-        'Usage: local-sfn [options] [inputs...]\n\nExecute an Amazon States Language state machine with the given inputs.\nThe result of each execution will be output in a new line and in the same order\nas its corresponding input.\n\nArguments:\n  inputs                         Input data for the state machine, can be any\n                                 valid JSON value. Each input represents a\n                                 state machine execution.\n  \n                                 When reading from the standard input, if the\n                                 first line can be parsed as a single JSON\n                                 value, then each line will be considered as an\n                                 input. Otherwise, the entire standard input\n                                 will be considered as a single JSON input.\n\nOptions:\n  -V, --version                  Print the version number and exit.\n  -d, --definition <definition>  A JSON definition of a state machine.\n  -f, --definition-file <path>   Path to a file containing a JSON state machine\n                                 definition.\n  -t, --override-task <mapping>  Override a Task state to run an executable\n                                 file or script, instead of calling the service\n                                 specified in the \'Resource\' field of the state\n                                 definition. The mapping value has to be\n                                 provided in the format\n                                 [TaskStateToOverride]:[path/to/override/script].\n                                 The override script will be passed the input\n                                 of the Task state as first argument, which can\n                                 then be used to compute the task result. The\n                                 script must print the task result as a JSON\n                                 value to the standard output.\n  -w, --override-wait <mapping>  Override a Wait state to pause for the\n                                 specified amount of milliseconds, instead of\n                                 pausing for the duration specified in the\n                                 state definition. The mapping value has to be\n                                 provided in the format\n                                 [WaitStateToOverride]:[number].\n  --context <json>               A JSON object that will be passed to each\n                                 execution as the context object.\n  --context-file <path>          Path to a file containing a JSON object that\n                                 will be passed to each execution as the\n                                 context object.\n  --no-jsonpath-validation       Disable validation of JSONPath strings in the\n                                 state machine definition.\n  --no-arn-validation            Disable validation of ARNs in the state\n                                 machine definition.\n  --no-validation                Disable validation of the state machine\n                                 definition entirely. Use this option at your\n                                 own risk, there are no guarantees when passing\n                                 an invalid or non-standard definition to the\n                                 state machine. Running it might result in\n                                 undefined/unsupported behavior.\n  -h, --help                     Print help for command and exit.\n\nExit codes:\n  0	All executions ran successfully.\n  1	An error occurred before the state machine could be executed.\n  2	At least one execution had an error.\n\nExample calls:\n  $ local-sfn -f state-machine.json \'{ "num1": 2, "num2": 2 }\'\n  $ local-sfn -f state-machine.json -t SendRequest:./override.sh -w WaitResponse:2000 \'{ "num1": 2, "num2": 2 }\'\n  $ cat inputs.txt | local-sfn -f state-machine.json\n'
+        'Usage: local-sfn [options] [inputs...]\n\nExecute an Amazon States Language state machine with the given inputs.\nThe result of each execution will be printed in a new line and in the same\norder as its corresponding input.\n\nArguments:\n  inputs                          Input data for the state machine, can be any\n                                  valid JSON value. Each input represents a\n                                  state machine execution.\n  \n                                  When reading from the standard input, if the\n                                  first line can be parsed as a single JSON\n                                  value, then each line will be considered as\n                                  an input. Otherwise, the entire standard\n                                  input will be considered as a single JSON\n                                  input.\n\nOptions:\n  -V, --version                   Print the version number and exit.\n  -d, --definition <definition>   A JSON definition of a state machine.\n  -f, --definition-file <path>    Path to a file containing a JSON state\n                                  machine definition.\n  -t, --override-task <mapping>   Override a Task state to run an executable\n                                  file or script, instead of calling the\n                                  service specified in the \'Resource\' field of\n                                  the state definition. The mapping value has\n                                  to be provided in the format\n                                  [TaskStateToOverride]:[path/to/override/script].\n                                  The override script will be passed the input\n                                  of the Task state as first argument, which\n                                  can then be used to compute the task result.\n                                  The script must print the task result as a\n                                  JSON value to the standard output.\n  -w, --override-wait <mapping>   Override a Wait state to pause for the\n                                  specified amount of milliseconds, instead of\n                                  pausing for the duration specified in the\n                                  state definition. The mapping value has to be\n                                  provided in the format\n                                  [WaitStateToOverride]:[number].\n  -r, --override-retry <mapping>  Override a \'Retry\' field to pause for the\n                                  specified amount of milliseconds, instead of\n                                  pausing for the duration specified by the\n                                  retry policy. The mapping value has to be\n                                  provided in the format\n                                  [NameOfStateWithRetryField]:[number].\n  --context <json>                A JSON object that will be passed to each\n                                  execution as the context object.\n  --context-file <path>           Path to a file containing a JSON object that\n                                  will be passed to each execution as the\n                                  context object.\n  --no-jsonpath-validation        Disable validation of JSONPath strings in the\n                                  state machine definition.\n  --no-arn-validation             Disable validation of ARNs in the state\n                                  machine definition.\n  --no-validation                 Disable validation of the state machine\n                                  definition entirely. Use this option at your\n                                  own risk, there are no guarantees when\n                                  passing an invalid or non-standard definition\n                                  to the state machine. Running it might result\n                                  in undefined/unsupported behavior.\n  -h, --help                      Print help for command and exit.\n\nExit codes:\n  0	All executions ran successfully.\n  1	An error occurred before the state machine could be executed.\n  2	At least one execution had an error.\n\nExample calls:\n  $ local-sfn -f state-machine.json \'{ "num1": 2, "num2": 2 }\'\n  $ local-sfn -f state-machine.json -t SendRequest:./override.sh -w WaitResponse:2000 \'{ "num1": 2, "num2": 2 }\'\n  $ cat inputs.txt | local-sfn -f state-machine.json\n'
       );
     });
   });

src/cli/ArgumentParsers.ts

@@ -1,6 +1,10 @@
 import type { Command } from 'commander';
 import type { StateMachineDefinition } from '../typings/StateMachineDefinition';
-import type { TaskStateResourceLocalHandler, WaitStateTimeOverride } from '../typings/StateMachineImplementation';
+import type {
+  TaskStateResourceLocalHandler,
+  WaitStateTimeOverride,
+  RetryIntervalOverrides,
+} from '../typings/StateMachineImplementation';
 import type { JSONValue } from '../typings/JSONValue';
 import type { Context } from '../typings/Context';
 import { readFileSync } from 'fs';
@@ -85,6 +89,20 @@ function parseOverrideWaitOption(value: string, previous: WaitStateTimeOverride
   return previous;
 }
 
+function parseOverrideRetryOption(value: string, previous: RetryIntervalOverrides = {}): RetryIntervalOverrides {
+  const [stateName, duration] = value.split(':');
+
+  // eslint-disable-next-line @typescript-eslint/ban-ts-comment
+  // @ts-ignore
+  if (!isNaN(duration)) {
+    previous[stateName] = Number(duration);
+  } else {
+    previous[stateName] = duration.split(',').map(Number);
+  }
+
+  return previous;
+}
+
 function parseContextOption(command: Command, context: string) {
   const jsonOrError = tryJSONParse<Context>(context);
 
@@ -137,6 +155,7 @@ export {
   parseDefinitionFileOption,
   parseOverrideTaskOption,
   parseOverrideWaitOption,
+  parseOverrideRetryOption,
   parseInputArguments,
   parseContextOption,
   parseContextFileOption,

src/cli/CLI.ts

@@ -10,6 +10,7 @@ import {
   parseInputArguments,
   parseOverrideTaskOption,
   parseOverrideWaitOption,
+  parseOverrideRetryOption,
   parseContextOption,
   parseContextFileOption,
 } from './ArgumentParsers';
@@ -23,7 +24,7 @@ function makeProgram() {
     .name('local-sfn')
     .description(
       `Execute an Amazon States Language state machine with the given inputs.
-The result of each execution will be output in a new line and in the same order as its corresponding input.`
+The result of each execution will be printed in a new line and in the same order as its corresponding input.`
     )
     .helpOption('-h, --help', 'Print help for command and exit.')
     .configureHelp({ helpWidth: 80 })
@@ -63,6 +64,12 @@ Example calls:
         'Override a Wait state to pause for the specified amount of milliseconds, instead of pausing for the duration specified in the state definition. The mapping value has to be provided in the format [WaitStateToOverride]:[number].'
       ).argParser(parseOverrideWaitOption)
     )
+    .addOption(
+      new Option(
+        '-r, --override-retry <mapping>',
+        "Override a 'Retry' field to pause for the specified amount of milliseconds, instead of pausing for the duration specified by the retry policy. The mapping value has to be provided in the format [NameOfStateWithRetryField]:[number]."
+      ).argParser(parseOverrideRetryOption)
+    )
     .addOption(
       new Option(
         '--context <json>',

src/cli/CommandHandler.ts

@@ -23,6 +23,7 @@ async function commandAction(inputs: JSONValue[], options: ParsedCommandOptions,
       overrides: {
         taskResourceLocalHandlers: options.overrideTask,
         waitTimeOverrides: options.overrideWait,
+        retryIntervalOverrides: options.overrideRetry,
       },
       context: options.context ?? options.contextFile,
     });

src/typings/CLI.ts

@@ -1,12 +1,17 @@
 import type { Context } from './Context';
 import type { StateMachineDefinition } from './StateMachineDefinition';
-import type { TaskStateResourceLocalHandler, WaitStateTimeOverride } from './StateMachineImplementation';
+import type {
+  TaskStateResourceLocalHandler,
+  WaitStateTimeOverride,
+  RetryIntervalOverrides,
+} from './StateMachineImplementation';
 
 export type ParsedCommandOptions = {
   definition: StateMachineDefinition;
   definitionFile: StateMachineDefinition;
   overrideTask: TaskStateResourceLocalHandler;
   overrideWait: WaitStateTimeOverride;
+  overrideRetry: RetryIntervalOverrides;
   context: Context;
   contextFile: Context;
   jsonpathValidation: boolean;