jaredgorski / Arpx
Programming Languages
Projects that are alternatives of or similar to Arpx
Description
arpx runs PROCESSES as they are defined in PROFILES. PROFILES allow for the configuration of PROCESSES, MONITORS, and ACTIONS, which work together to execute commands, watch for triggering conditions, and respond to those triggering conditions with new commands.
PROFILES can be run entirely or a single PROCESS can be run from within a PROFILE. If no PROFILE is defined, arpx will look for a file named arpx.yaml
within the current working directory to run. PROCESSES can be configured to execute alone (blocking), run concurrently, depend on other PROCESSES, and perform ACTIONS when specific conditions are met.
Usage
General program information
Command | Info |
---|---|
-h, --help | Output a usage message and exit. |
-V | Output the version number of arpx and exit. |
Options
Command | Info |
---|---|
-f PROFILE, --file=PROFILE | Execute a PROFILE at the given filepath. Defaults to ./arpx.yaml . |
-p PROCESS, --process=PROCESS | Execute a single PROCESS from within the current PROFILE. |
Profile configuration
PROFILES can be named arpx.yaml
or formatted as <my-prefix>.arpx.yaml
. PROFILES are currently the primary mode of configuration for arpx runtimes, at least until a more scriptable/less verbose interface is developed.
entrypoint: [NAME OF PROCESS] // Configure a single PROCESS to be run as an "entrypoint" to the profile.
processes: // Define PROCESSES.
- name: [NAME OF PROCESS] // Add a unique name to identify the PROCESS within the arpx runtime.
command: [COMMAND] // The command to execute.
color: [COLOR] // Output color. Receives [ black, blue, green, red, cyan, magenta, yellow, white, <ansi 256 number>, <rgb in format 255,255,255> ]
cwd: [PATH] // Directory in which to execute command.
blocking: [TRUE|(FALSE)] // Whether the PROCESS should block the main thread or run concurrently.
silent: [TRUE|(FALSE)] // Whether to silence logs for the PROCESS.
onsucceed: [ACTION] // ACTION to execute if PROCESS exits with success. To execute an existing PROCESS, use `process:` followed by the PROCESS name.
onfail: [ACTION] // ACTION to execute if PROCESS exits with failure. To execute an existing PROCESS, use `process:` followed by the PROCESS name.
monitors: // Configure MONITORS for specific PROCESSES.
- process: [NAME OF PROCESS] // Specify the PROCESS to MONITOR.
condition: [COMMAND] // Define bash condition which, on successful exit, triggers ACTIONS.
actions: // Specify ACTIONS to execute when triggering conditions are met.
[ACTIONS] // See `Actions` section below for an overview on built-in and custom ACTIONS.
actions: // Define custom ACTIONS which can be activated by MONITORS under triggering conditions.
- name: [NAME OF ACTION] // Add a unique name to identify the ACTION within the arpx runtime.
command: [COMMAND] // The command to execute.
color: [COLOR] // Output color. Receives [ black, blue, green, red, cyan, magenta, yellow, white, <ansi 256 number>, <rgb in format 255,255,255> ]
cwd: [PATH] // Directory in which to execute command.
silent: [TRUE|(FALSE)] // Whether to silence logs for the ACTION.
stdin: [STDIN] // Enter some stdin when the ACTION is triggered.
onsucceed: [ACTION] // ACTION to execute if ACTION exits with success. To execute an existing PROCESS, use `process:` followed by the PROCESS name.
onfail: [ACTION] // ACTION to execute if ACTION exits with failure. To execute an existing PROCESS, use `process:` followed by the PROCESS name.
Example profile - script.arpx.yaml:
processes:
- name: loop1
color: red
command: |
for i in {1..5}
do
sleep 1
echo "Loop1 $i"
done
- name: loop3
color: blue
command: |
for i in {1..5}
do
sleep 1
echo "Loop3 $i"
done
monitors:
- process: loop1
condition: '[[ "$LOG_LINE" =~ "Loop1 5" ]]'
actions:
- loop2
actions:
- name: loop2
color: green
command: |
for i in {1..3}
do
sleep 1
echo "Loop2 $i"
done
exit
processes:
- name: loop1
color: red
command: |
for i in {1..5}
do
sleep 1
echo "Loop1 $i"
done
blocking: true // Added
- name: loop3
color: blue
command: |
for i in {1..5}
do
sleep 1
echo "Loop3 $i"
done
monitors:
- process: loop1
condition: '[[ "$LOG_LINE" =~ "Loop1 5" ]]'
actions:
- loop2
actions:
- name: loop2
color: green
command: |
for i in {1..3}
do
sleep 1
echo "Loop2 $i"
done
exit
entrypoint: loop1 // Added
processes:
- name: loop1
color: red
command: |
for i in {1..5}
do
sleep 1
echo "Loop1 $i"
done
onsucceed: process:loop2 // Added
- name: loop2
color: green
command: |
for i in {1..3}
do
sleep 1
echo "Loop2 $i"
done
exit
onsucceed: process:loop3 // Added
- name: loop3
color: blue
command: |
for i in {1..5}
do
sleep 1
echo "Loop3 $i"
done
Processes
PROCESSES are the primary commands arpx will manage. PROCESSES can be run blockingly or concurrently, and can be run one at a time with the -p
option.
To run an individual PROCESS named my-process
contained in a file named arpx.yaml
in the current working directory, execute:
$ arpx -p my-process
To run individual PROCESSES named my-process-1
and my-process-
contained in a file named arpx.yaml
in the current working directory, execute:
$ arpx -p my-process-1 my-process-2
To run all PROCESSES (or entrypoint PROCESS) contained in a file named my.arpx.yaml
, execute:
$ arpx -f ~/path/to/my.arpx.yaml
Process properties:
- name: Name of the PROCESS.
- command: Command to execute when PROCESS is initiated.
- color Output color. Receives [ black, blue, green, red, cyan, magenta, yellow, white, <ansi 256 number>, <rgb in format 255,255,255> ].
-
cwd: Working directory in which to execute PROCESS
command
. -
blocking: Whether the PROCESS should block the main thread or run concurrently. Blocking PROCESSES will run in the order in which they are defined in
arpx.yaml
, so long as they precede any non-blocking PROCESSES. Non-blocking PROCESSES will run concurrently to to other PROCESSES and will therefore not block the main thread from initiating the remainder of the defined PROCESSES. Settingblocking
totrue
makes it possible to run PROCESSES in order, rather than concurrently. -
silent: Whether the PROCESS should propagate stdout and stderr from the
command
to the arpx stdout. -
onsucceed: An ACTION to initiate if the current PROCESS
command
exits successfully. To execute an existing PROCESS, useprocess:
followed by the PROCESS name. -
onfail: An ACTION to initiate if the current PROCESS
command
exits with failure. To execute an existing PROCESS, useprocess:
followed by the PROCESS name.
Monitors
MONITORS watch for conditions in a given PROCESS and perform ACTIONS if/when those conditions are met. MONITORS are configured by defining a condition and actions to execute when the condition exits successfully.
Monitor properties:
- process: Name of the PROCESS that this MONITOR's CONDITION should apply to.
-
condition: Shell condition which, upon a successful exit status, triggers ACTIONS. Conditions are checked with each line a program logs from
stdout
orstderr
. The output of the current line is available within thecondition
script via the$LOG_LINE
variable. - actions: List of ACTIONS to initiate if this MONITOR's CONDITION exits with success.
Actions
ACTIONS are new PROCESSES which can be executed when triggered by a MONITOR. There are built-in actions available to all MONITORS specified below. Custom ACTIONS can also be defined.
Built-in actions
- exit: Exit arpx.
-
kill: Exit the current PROCESS. Does not work with
onsucceed
oronfail
. -
respawn: Exit and restart the current PROCESS. If used with
onsucceed
oronfail
on an ACTION, arpx will attempt to spawn a PROCESS with a name matching the current ACTION. -
silence: Silence the current log. Does not work with
onsucceed
oronfail
.
Custom
Custom ACTIONS can define new tasks to be executed if/when triggering conditions are met. Currently, the only type of ACTION available is shell
, which allows for defining a shell command to run when the current ACTION is activated. If ACTION is called via onsucceed
or onfail
, stdin
will not apply.
Custom action properties:
- name: Name of the ACTION.
- command: Command to execute when ACTION is initiated.
- color Output color. Receives [ black, blue, green, red, cyan, magenta, yellow, white, <ansi 256 number>, <rgb in format 255,255,255> ].
-
cwd: Working directory in which to execute ACTION
command
. -
silent: Whether the ACTION should propagate stdout and stderr from the
command
to the arpx stdout. -
stdin: Enter some stdin. Allows for automatically replying to prompts from a PROCESS.
stdin
does not apply to ACTIONS called byonsucceed
oronfail
. -
onsucceed: An ACTION to initiate if the current ACTION
command
exits successfully. To execute an existing PROCESS, useprocess:
followed by the PROCESS name. -
onfail: An ACTION to initiate if the current ACTION
command
exits with failure. To execute an existing PROCESS, useprocess:
followed by the PROCESS name.
Applications and purpose
Some potential applications:
- Selectively silence logging output for programs or scripts
- Automate build process
- Run multiple programs or scripts concurrently
- Manage local development environment with multiple dependent services as one process
- Run scripts in a particular order
- Automate spinning up multiple processes which depend on each other
- Handle errors in scripts automatically
arpx is useful for automatically handling errors, suppressing stdout/stderr output, scheduling processes relative to each other, and more. It was originally concieved for the purpose of automatically handling errors while running a local development environment with multiple dependent services. The goal is that arpx should be generally useful, so please open issues for enhancements with a mind toward powerful, general utility.
Contributing
This project is my first program in Rust. It's rough around the edges and has not been styleguided yet, but "simplicity" and "clarity" are words that come to mind when I envision what it should look like down the road. Contributions and suggestions should reflect the Unix Philosophy.
Integrations
Programmatic
- arpxjs: Programmatic process automation, relation, and multiplexing for Node.js