From c7a6772b2b23a64800f493a4502994d8ad7ec09f Mon Sep 17 00:00:00 2001 From: xdrm-brackets Date: Sat, 7 Jul 2018 17:38:26 +0200 Subject: [PATCH] remove old builders (bash) + update readme --- README.md | 111 +++++++++++++++++++++++++++++++++++++++---- build-controllers.sh | 42 ---------------- build-types.sh | 31 ------------ 3 files changed, 101 insertions(+), 83 deletions(-) delete mode 100644 build-controllers.sh delete mode 100644 build-types.sh diff --git a/README.md b/README.md index 4ace7f0..493eb00 100644 --- a/README.md +++ b/README.md @@ -2,22 +2,113 @@ -**Aicra** is a self-working API coded in *Go*: +**Aicra** is a self-working framework coded in *Go* that allows anyone to create a fully featured REST API. It features : + +- type checking + +- authentication management + +- rich argument management (url slash-separated, urlencoded, form-data, json) + +- nested routes + +- request and response interfaces + +- a project builder (cf. *aicra*) + +- Optional arguments and default values + +- ... + + + +It is based over some of the following concepts. + +| concept | explanation | +|---|---| +| meaningful defaults | Defaults and default values work without further understanding | +| config-driven | Avoid information duplication. Automate anything that can be without losing control. Have *one* configuration that summarizes the whole project, its behavior and its automation flow. | -- It allows anyone to create a fully featured REST API -- it can be used in *Go* as a library, or as a proxy to launch external commands (*e.g. php scripts*) -It is based on the *all-in-config* idea, where you only have a configuration file, and your implementation and it works without no further work. > A working example is available [here](https://git.xdrm.io/example/gfw) + +#### 1. Installation + +You need a recent machine with `go` installed. + +> This package has not been tested under the version **1.10**. + + + +##### (1) Installation + +Run the following command to fetch and install the package : + +```bash +go get -u git.xdrm.io/go/aicra +``` + +It should now be available locally and available for your imports. + + + +You should then install the project builder to help you manage your projects, run the following command : + +```bash +go install git.xdrm.io/go/aicra/cmd/aicra +``` + +The executable `aicra` will be placed into your `$GOPATH/bin` folder, if added to your environment PATH it should be available as a standalone command in your terminal. If not, you can simply run `$GOPATH/bin/aicra` to use the command or create a symlink into `/usr/local/bin` or the PATH folder of your choice for less characters to type. + + + +#### 2. Setup a project + +To create a project using **aicra**, simply create an empty folder. Then you'll have to create a `manifest.json` file containing your API description. To write your manifest file, follow this [example](https://git.xdrm.io/example/aicra/src/master/manifest.json). + + + +##### (1) Controllers + +For each *uri*, you'll have to place your implementation into the local `root` folder following the following naming convention : add `i.go` at the end of the route. + +> **Example** - `/path/to/some/uri` will be implemented in the *./root* local folder inside the file : `/path/to/some/urii.go`. + +A fully working example is available [here](https://git.xdrm.io/example/aicra). + + + +##### (2) Custom types + +If you want to create custom types for the type checker or override built-in types place them inside the `./custom-types` folder. You can check what structure to follow by looking at the [built-in types](https://git.xdrm.io/go/aicra/src/master/checker/default). + + + +#### 3. Build your project + +After each controller or custom type edition, you'll have to rebuild the project. This can be achieved through the command-line builder. +Usage is `aicra [options] /path/to/your/project`. + +Options: + +- `-c controller/path` - overrides the default controllers path ; default is `./root` + +- `-t custom/types` - overrides the default custom types path ; default is `./custom-types` + + + + + + ##### changelog -- [x] human-readable json configuration -- [x] nested routes (*i.e. `/user/:id:` and `/user/post/​:id:​`*) -- [ ] nested URL arguments (*i.e. `/user/:id:` and `/user/:id:/post/​:id:​`*) +- [x] human-readable json configuration +- [x] nested routes (*i.e. `/user/:id:` and `/user/post/​:id:​`*) +- [ ] nested URL arguments (*i.e. `/user/:id:` and `/user/:id:/post/​:id:​`*) - [x] useful http methods: GET, POST, PUT, DELETE - [x] manage URL, query and body arguments: - [x] multipart/form-data (variables and file uploads) @@ -25,8 +116,8 @@ It is based on the *all-in-config* idea, where you only have a configuration fi - [x] application/json - [x] required vs. optional parameters with a default value - [x] parameter renaming -- [ ] generic authentication system (*i.e. you can override the built-in one*) -- [x] generic type check (*i.e. implement custom types alongside built-in ones*) +- [ ] generic authentication system (*i.e. you can override the built-in one*) +- [x] generic type check (*i.e. implement custom types alongside built-in ones*) - [ ] built-in types - [x] `any` - wildcard matching all values - [x] `int` - any number (*e.g. float, int, uint*) @@ -35,4 +126,4 @@ It is based on the *all-in-config* idea, where you only have a configuration fi - [ ] `` - array containing **only** elements matching `a` type - [ ] `` - map containing **only** keys of type `a` and values of type `b` (*a or b can be ommited*) - [x] generic controllers implementation (shared objects) -- [x] response interface +- [x] response interface \ No newline at end of file diff --git a/build-controllers.sh b/build-controllers.sh deleted file mode 100644 index 861f037..0000000 --- a/build-controllers.sh +++ /dev/null @@ -1,42 +0,0 @@ -#!/bin/bash - -# (1) Check argument -#--------------------------------------------------------# -if [ "$#" -lt 1 -o ! -d "$1" ]; then - echo -e "\e[33mERROR\e[0m missing parameter\n" - echo -e "+ expected first argument to be the controller's folder" - exit 1; -fi - - - -# (1) Get controller path # -BASE_DIR="`realpath $(pwd)`" -CTL_PATH="`realpath $1`"; - -# (2) List go files # -cd $CTL_PATH -GO_FILES="`ls *i.go **/*i.go 2>/dev/null`" - -# (3) Create target directory in execution dir # -mkdir -p $BASE_DIR/controllers; - -# (4) Build each file # -d=1 -for file in $GO_FILES; do - ctl="${file%.*}" # remove extension from path - echo -e "($d) Building \e[33m$ctl\e[0m"; - # build into execution dir - go build -buildmode=plugin -ldflags "-s -w" -o "$BASE_DIR/controllers/$ctl.so" ./$file; - - # Manage failure - if [ "$?" -ne "0" ]; then - echo -e "\e[31m/!\\ \e[0merror building \e[33m$ctl\e[0m\n" - fi - - d=""`expr $d + 1`"" -done; - -# (5) ACK # -echo -e "\n[ \e[32mfinished\e[0m ]\n" -echo -e "files are located inside the relative \e[33m./controllers\e[0m directory" \ No newline at end of file diff --git a/build-types.sh b/build-types.sh deleted file mode 100644 index aa32e26..0000000 --- a/build-types.sh +++ /dev/null @@ -1,31 +0,0 @@ -#!/bin/bash - -# (1) Get default path # -DEFAULT_PATH="`realpath $GOPATH`/src/git.xdrm.io/go/aicra/checker/default"; -# fail if do not exist -test -d $DEFAULT_PATH || (echo "$DEFAULT_PATH does not exists.. aborting"; exit 1) || exit 1; - -# (2) List go files # -GO_FILES="`ls $DEFAULT_PATH/**/*.go`" - -# (3) Create target directory # -mkdir -p ./types; - -# (4) Build each file # -d=1 -for Type in $GO_FILES; do - plugin_name="`basename $(dirname $Type)`" - echo -e "($d) Building \e[33m$plugin_name\e[0m"; - go build -buildmode=plugin -o "./types/$plugin_name.so" $Type; - - # Manage failure - if [ "$?" -ne "0" ]; then - echo -e "\e[31m/!\\ \e[0merror building \e[33m$plugin_name\e[0m\n" - fi - - d=""`expr $d + 1`"" -done; - -# (5) ACK # -echo -e "\n[ \e[32mfinished\e[0m ]\n" -echo -e "files are located inside the relative \e[33m./types\e[0m directory" \ No newline at end of file