diff --git a/README.md b/README.md index 843db46..d06583c 100644 --- a/README.md +++ b/README.md @@ -14,6 +14,7 @@ We have some guides and general documentation in the [docs](docs/) directory. Am - [Tests](docs/tests.md) - [HTTP Router](docs/router.md) - [Template engine](docs/template.md) +- [Script integrations](docs/util.md) - [List of security fixes](docs/sec-fixes/) ## Dependencies diff --git a/docs/running.md b/docs/running.md index f6df44b..b6cbc97 100644 --- a/docs/running.md +++ b/docs/running.md @@ -9,3 +9,6 @@ The arg parsing is a bit rudimentary atm. Assume only one option supported per i - `debug` shows stderr (useful for debugging) - `debuggier` shows stderr and calltrace - `shell` drops you into an environment practically equivalent to the runtime +- `utils` lists all available [utilities](./util.md) (scripts which integrate into the + standard HTTP.sh environment, but are strictly for CLI use. Useful for administrative tasks.) +- ` [params]` launches an utility, if it's available diff --git a/docs/util.md b/docs/util.md new file mode 100644 index 0000000..b11dc2c --- /dev/null +++ b/docs/util.md @@ -0,0 +1,45 @@ +# utils: integrating scripts with http.sh + +HTTP.sh provides a number of useful APIs designed to make interfacing with HTTP and browsers easier. +Some of those (especially notORM) are also useful in a CLI environment, to help with migrations and +other administrative tasks. + +Utils integrate into HTTP.sh through calling the main script, with the utility name as the first +parameter. So, for `meow.sh` the invocation would be `./http.sh meow`, or `./http.sh meow [params]` +if the util takes any parameters. + +Utils are automagically started within the environment, and otherwise work like normal scripts. +Of note: + +- `$0` is always the `./http.sh` invocation, not your script name +- script name is instead stored in `$HTTPSH_SCRIPTNAME` +- `$@` contain parameters to the utility, not a full invocation. +- at the present, only the `master.sh` config is loaded +- the environment is equivalent to `./http.sh shell` + +A list of utilities can be obtained by calling `./http.sh utils`. + +## Built-in utils + +The following scripts are generic helpers shipped with HTTP.sh. We hope they'll come in handy. + +### notORM + +WIP. Currently can only dump a store out to the terminal: + +```bash +$ ./http.sh notORM dump storage/new.dat +declare -a data=([0]="0" [1]="domi" [2]="http://sdomi.pl/" [3]="" [4]="XOaj44smtzCg1p88fgG7bEnMeTNt361wK8Up4BKEiU747lcNIuMAez60zEiAaALWMwzcQ6" [5]="0" [6]="meow~" [7]="RCszUuBXQI") + (…) +``` + +### bump + +Acknowledges a version after a HTTP.sh update. Takes no parameters. + +## Future plans + +- List a description for each util on the `./http.sh utils` page. This would require storing more + metadata on the utils, TBD. +- more 1st-party utils! +- more work on notORM util, ideally it should allow one to do all actions on the DB diff --git a/http.sh b/http.sh index b3877ef..34a9cab 100755 --- a/http.sh +++ b/http.sh @@ -59,7 +59,12 @@ fi source config/master.sh if [[ "$HTTPSH_VERSION" != "${cfg[init_version]}" ]]; then - echo "WARN: HTTP.sh was updated since this instance was initialized (config v${cfg[init_version]:-(none)}, runtime v$HTTPSH_VERSION). There may be breaking changes. Edit cfg[init_version] in config/master.sh to remove this warning." + echo "WARN: HTTP.sh was updated since this instance was initialized (config v${cfg[init_version]:-(none)}, runtime v$HTTPSH_VERSION). There may be breaking changes. + +Check for breaking changes (announced on IRC and in `git log`), +then use this to ACK the message: + +./http.sh bump" fi while read i; do @@ -102,6 +107,32 @@ if [[ "$1" == 'shell' ]]; then exit 0 fi +if [[ "$1" == "utils" ]]; then # list all available utils + # would be cool to make this more generic + ls "${cfg[namespace]}/util/" "src/util" + exit 0 +fi + +for path in "${cfg[namespace]}/util/" "src/util/"; do + HTTPSH_SCRIPTNAME="$(basename "$1")" + if [[ -x "$path$HTTPSH_SCRIPTNAME.sh" ]]; then + shift + shopt -s extglob + source src/account.sh + source src/mail.sh + source src/mime.sh + source src/misc.sh + source src/notORM.sh + source src/template.sh + source "${cfg[namespace]}/config.sh" + source "$path$HTTPSH_SCRIPTNAME.sh" + exit 0 + elif [[ -f "$path$HTTPSH_SCRIPTNAME.sh" ]]; then + echo "[WARN] util '$1' found, but not executable. Ignoring..." >&2 + fi +done +unset path HTTPSH_SCRIPTNAME + cat <&2 _ _ _______ _______ _____ ______ _ _ | | | |_______|_______| _ \/ ___/| | | | diff --git a/src/util/bump.sh b/src/util/bump.sh new file mode 100755 index 0000000..7db026b --- /dev/null +++ b/src/util/bump.sh @@ -0,0 +1,8 @@ +#!/bin/bash +if [[ "$HTTPSH_VERSION" != "${cfg[init_version]}" ]]; then + sed -i '/cfg\[init_version\]=/d' config/master.sh + echo "cfg[init_version]=$HTTPSH_VERSION" >> "config/master.sh" + echo "Version bumped. I hope you checked for breaking changes!" +else + echo "All good! :3" +fi diff --git a/src/util/notORM.sh b/src/util/notORM.sh new file mode 100755 index 0000000..27a9120 --- /dev/null +++ b/src/util/notORM.sh @@ -0,0 +1,11 @@ +#!/bin/bash +if [[ ! "$1" ]]; then + echo "usage: $0 $HTTPSH_SCRIPTNAME [params] + +Action can be one of: + dump - dump the contents of a notORM store" + exit 1 +elif [[ "$1" == dump ]]; then + x() { declare -p data; } + data_iter "$2" { } x +fi diff --git a/src/version.sh b/src/version.sh index c290b98..3285da3 100644 --- a/src/version.sh +++ b/src/version.sh @@ -1,2 +1,2 @@ #!/usr/bin/env bash -HTTPSH_VERSION=0.97.2 +HTTPSH_VERSION=0.97.3