Update readme

This commit is contained in:
Adrien Marquès 2019-09-26 14:28:11 +02:00
parent 4c5f13933c
commit 4eb9f58074
1 changed files with 60 additions and 362 deletions

422
README.md
View File

@ -7,146 +7,96 @@
[![Build Status](https://ci.migration.xdrm.io/buildStatus/icon?job=aicra%2F0.2.0)](.)
**Aicra** is a *configuration-driven* REST **API engine** in *Go* that allows you to create a fully featured API.
**Aicra** is a *configuration-driven* **web framework** written in Go that allows you to create a fully featured REST API.
The whole API management is done for you from a configuration file describing your API, you just need to implement :
The whole management is done for you from a configuration file describing your API, you're left with implementing :
- controllers
- optionnally middle-wares (_e.g. authentication, csrf_)
- and optionnally type checkers to check input parameters
- the <u>controllers</u>
- the <u>middle-wares</u> (_e.g. authentication, csrf_)
- and optionnally the <u>type checkers</u> to check if input values follows some rules
> There is 2 available drivers that will load your implementations. The `plugin` driver is for Go programmers, the `generic` one is for any language (it uses standard input and output).
The aicra server fulfills the `net/http` [Server interface](https://golang.org/pkg/net/http/#Server).
The engine has been designed with the following concepts in mind.
| concept | explanation |
|---|---|
| meaningful defaults | Defaults and default values work without further understanding |
| configuration driven | Avoid information duplication. Automate anything that can be automated without losing control. Have *one* configuration that summarizes the whole API, its behavior and its automation flow. |
> A example project is available [here](https://git.xdrm.io/example/aicra)
> A example project is available [here](https://git.xdrm.io/go/tiny-url-ex)
### Table of contents
<!-- toc -->
* [I. Installation](#i-installation)
* [1. Download and install the package](#1-download-and-install-the-package)
* [II. Setup a project](#ii-setup-a-project)
* [1. Compilation configuration](#1-compilation-configuration)
* [Example](#example)
* [2. API Configuration](#2-api-configuration)
* [Definition](#definition)
* [Input Arguments](#input-arguments)
* [1. Input types](#1-input-types)
* [2. Global Format](#2-global-format)
* [3. Example](#3-example)
* [3. Controllers](#3-controllers)
* [1. Plugin driver](#1-plugin-driver)
* [2. Generic driver](#2-generic-driver)
* [4. Middle-wares](#4-middle-wares)
* [1. Plugin driver](#1-plugin-driver-1)
* [2. Generic driver](#2-generic-driver-1)
* [5. Type checkers](#5-type-checkers)
* [1. Plugin driver](#1-plugin-driver-2)
* [2. Generic driver](#2-generic-driver-2)
* [III. Build your project](#iii-build-your-project)
* [IV. Main](#iv-main)
* [V. Change Log](#v-change-log)
- [I/ Installation](#i-installation)
- [II/ Development](#ii-development)
* [1) Main executable](#1-main-executable)
* [2) API Configuration](#2-api-configuration)
- [Definition](#definition)
+ [Input Arguments](#input-arguments)
- [1. Input types](#1-input-types)
- [2. Global Format](#2-global-format)
- [III/ Change Log](#iii-change-log)
<!-- tocstop -->
### I. Installation
### I/ Installation
You need a recent machine with `go` [installed](https://golang.org/doc/install).
You need a recent machine with `go` [installed](https://golang.org/doc/install). This package has not been tested under the version **1.10**.
> This package has not been tested under the version **1.10**.
#### 1. Download and install the package
```bash
go get -u git.xdrm.io/go/aicra/cmd/aicra
```
The library should now be available locally as `git.xdrm.io/go/aicra` your imports. Moreover, the **project compiler** have been installed as the `aicra` command.
> 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 symbolic link into `/usr/local/bin` for instance.
The library should now be available as `git.xdrm.io/go/aicra` in your imports.
### II. Setup a project
The default project structure is :
```bash
├── main.go # entry point
|
├── aicra.json # server configuration file
├── api.json # API configuration file
|
├── middleware # middleware implementations
├── controller # controller implementations
└── type # custom type checkers
```
### II/ Development
#### 1) Main executable
#### 1. Compilation configuration
The main executable will declare and run the aicra server, it might look quite like the code below.
The `aicra.json` configuration file defines where are located your controllers, type checkers, and middle-wares ; also it contains what driver you want to use, you have 2 choices :
```go
package main
import (
"log"
"net/http"
1. **plugin** - for Go implementations (_c.f. [go plugin system](https://golang.org/pkg/plugin/)_)
2. **generic** - for any language implementation (uses standard input and output)
"git.xdrm.io/go/aicra"
"git.xdrm.io/go/aicra/typecheck/builtin"
"git.xdrm.io/go/aicra/api"
)
func main() {
// 1. build server
server, err := aicra.New("path/to/your/api/definition.json");
if err != nil {
log.Fatalf("Cannot build the aicra server: %v\n", err)
}
The file uses the [json](https://json.org/) format, each field is described in the table above.
// 2. add type checkers
server.Checkers.Add( builtin.NewAny() );
server.Checkers.Add( builtin.NewString() );
server.Checkers.Add( builtin.NewFloat64() );
| field | description | example value |
| ---------------------- | ------------------------------------------------------------ | --------------------------------- |
| `root` | The project folder path | `./some-path` or `/some/path` |
| `driver` | The driver to use for loading controllers, middlewares and type checkers | `plugin` or `generic` |
| `types`.`default` | Whether to load default types into the project | `true` or `false` |
| `types`.`folder` | The folder (relative to the project root) where type checkers' implementations are located | `./type` or `type` |
| `controllers`.`folder` | The folder (relative to the project root) where controllers' implementations are located | `./controller` or `controller` |
| `middlewares`.`folder` | The folder (relative to the project root) where middlewares' implementations are located | `./middleware` or `middleware` |
// 3. bind your implementations
server.HandleFunc(http.MethodGet, func(req api.Request, res *api.Response){
// ... process stuff ...
res.SetError(api.ErrorSuccess());
})
A sample file can be found [here](https://git.xdrm.io/example/aicra/src/master/aicra.json).
###### Example
In this example we have the controllers inside the `controller` folder, the middle-wares in the `middleware` folder and custom type checkers inside the `checker` folder, we want to load the built-in type checkers and are using the `plugin` driver. Also our project root is the relative current path `.` ; note that it is better using an absolute path as your project root.
```json
{
"root": ".",
"driver": "plugin",
"types": {
"default": true,
"folder": "checker"
},
"controllers": {
"folder": "controller.plugin"
},
"middlewares": {
"folder": "middleware.plugin"
}
// 4. launch server
log.Fatal( http.ListenAndServer("localhost:8181", server) )
}
```
#### 2. API Configuration
#### 2) API Configuration
The whole project behavior is described inside the `api.json` file. For a better understanding of the format, take a look at this working [template](https://git.xdrm.io/example/aicra/src/master/api.json). This file defines :
The whole project behavior is described inside a json file (_e.g. usually api.json_) file. For a better understanding of the format, take a look at this working [template](https://git.xdrm.io/go/tiny-url-ex/src/master/api.json). This file defines :
- resource routes and their methods
- every input for each method (called *argument*)
@ -182,11 +132,8 @@ For each method you will have to create fields described in the table above.
| `out` | The list of output data that will be returned by your controllers. It has the same syntax as the `in` field but is only use for readability purpose and documentation. | |
##### Input Arguments
###### 1. Input types
Input arguments defines what data from the HTTP request the method needs. Aicra is able to extract 3 types of data :
@ -239,248 +186,7 @@ In this example we want 3 arguments :
###### 3. Example
In this example you can see a pretty basic user/article REST API definition. The API let's you fetch, create, edit, and delete users and do the same for their articles. Users actions will be available at the uri `/user`, and `/article` for articles.
#### 3. Controllers
Controllers implement `Get`, `Post`, `Put`, and `Delete` methods, and have access to special variables injected in the argument list :
- `_HTTP_METHOD_` the request's HTTP method in uppercase
- `_SCOPE_` the scope filled by middle-wares
- `_AUTHORIZATION_` the request's **Authorization** header
Also special variables found in the return data are processed with special actions :
- `_REDIRECT_` will redirect to the URL contained in the variable
##### 1. Plugin driver
For each route, you'll have to place your implementation into the `controller` folder (according to the *aicra.json* configuration) following the naming convention : add `/main.go` at the end of the route.
> <u>Example</u> - the URI `/path/to/some/uri` is handled by the file `controller/path/to/some/uri/main.go`
>
> <u>Exception</u> - the URI `/` is handled by the file `controller/ROOT/main.go`
A sample directory structure is available [here](https://git.xdrm.io/example/aicra/src/master/controller.plugin).
Each controller must implement the [driver.Controller](https://godoc.org/git.xdrm.io/go/aicra/driver#Controller) interface. In addition you must declare the function `func Export() Controller` to allow dynamic loading of your controller.
**Example**
Here is a base code for any controllers
```go
package main
import (
"git.xdrm.io/go/aicra/driver"
"git.xdrm.io/go/aicra/api"
e "git.xdrm.io/go/aicra/err"
)
// Mockup controller implementation
type MyController interface{}
func Export() driver.Controller { return new(MyController) }
// GET method management
func (c MyController) Get(args api.Arguments) api.Response {
res := api.NewResponse()
res.Err = e.Success
return *res
}
// POST method management
func (c MyController) Post(args api.Arguments) api.Response { /*...*/ }
// PUT method management
func (c MyController) Put(args api.Arguments) api.Response { /*...*/ }
// DELETE method management
func (c MyController) Delete(args api.Arguments) api.Response { /*...*/ }
```
##### 2. Generic driver
This is the same as with the plugin driver but without `/main.go` at the end.
> <u>Example</u> - The URI `/path/to/some/uri` will be handled by the executable `controller/path/to/some/uri`.
> <u>Exception</u> - The URI `/` will be handled by the executable `controller/ROOT`.
A sample directory structure is available [here](https://git.xdrm.io/example/aicra/src/master/controller.generic).
The programs will be given useful data (*i.e. method and arguments*) through its input arguments :
| Argument index | Description | Examble value |
| -------------- | ------------------------------------------------------------ | ------------------------------------------------------------ |
| 1 | Uppercase HTTP method.<br>(_e.g. **$1** in bash, **argv[1]** in php_) | `GET`, `POST`, ... |
| 2 | JSON representation of the input arguments.<br>(_e.g. **$2** in bash, **argv[2]** in php_) | `{`<br> `"_SCOPE_": ["admin", "token"],`<br> `"somstring": "string",`<br> `"someint": 12`<br>`}` |
The standard output you will give back must be a key-value JSON representation of all the output variables.
#### 4. Middle-wares
In order for your project to manage authentication, the best solution is to use middle-wares, there are programs that updates a *Scope* (*i.e. a list of strings*) according to internal or persistent (*i.e.* database) information and the actual http request. They are all run before each request is forwarded to your controller. The Scopes are used to match the `scope` field in the configuration file and automatically block access to non-authenticated method calls. Scopes can also be used for implementation-specific behavior such as _CSRF_ management. Controllers have access to the scope through the variable `_SCOPE_`.
##### 1. Plugin driver
Each middleware must be **directly** inside the `middleware` folder (according to the _aicra.json_ configuration).
> Example - the `1-authentication` middleware will be inside `middleware/1-authentication/main.go`.
**Note** - middle-ware execution will be ordered by name. Prefixing your middle-wares with their order is a good practice.
A sample directory structure is available [here](https://git.xdrm.io/example/aicra/src/master/middleware.plugin).
Each middle-ware must implement the [driver.Middleware](https://godoc.org/git.xdrm.io/go/aicra/driver#Middleware) interface. In addition you must declare the function `func Export() Middleware` to allow dynamic loading of your middle-ware.
**Example**
Here is a base code for any middle-ware
```go
package main
import (
"git.xdrm.io/go/aicra/driver"
"net/http"
)
// Mockup middle-ware implementation
type MyMiddleware interface{}
func Export() driver.Middleware { return new(MyMiddleware) }
func (c MyMiddleware) Inspect(req http.Request, scope *[]string) {
// add scope according to request
if req.Header.Get("SomeHeader") {
*scope = append(*scope, "some-scope")
}
}
```
##### 2. Generic driver
This is the same as with the plugin driver but instead of without `/main.go` at the end.
> Example - the `1-authentication` middle-ware will be inside `middleware/1-authentication` where **1-authentication** is an executable
A sample directory structure is available [here](https://git.xdrm.io/example/aicra/src/master/middleware.generic).
The programs will be given useful data (*i.e. method and arguments*) through its input arguments :
| Argument index | Description | Examble value |
| -------------- | ------------------------------------------------------------ | ------------- |
| 1 | JSON representation of the input arguments.<br>(_e.g. **$1** in bash, **argv[1]** in php_) | ??? |
The standard output you will give back must be a JSON array containing the scope you want to add.
#### 5. Type checkers
In your configuration you can use built-in types (*e.g.* int, any, varchar, token, float, ...), but if you want project-specific ones, you can add your own types inside the `type` folder. You can check what structure to follow by looking at the [built-in types](https://git.xdrm.io/go/aicra/src/master/internal/checker/default). Also it is not required that you use built-in types, you can ignore them by setting `types.default = false` in the _aicra.json_ configuration.
Each type must be **directly** inside the `type` folder. The package name is arbitrary and does not have to match the name (but it is better if it is explicit), because the `Match()` method already does that.
##### 1. Plugin driver
Each type checker must be **directly** inside the `type` folder (according to the _aicra.json_ configuration).
> Example - the `number` type checker will be inside `type/number/main.go`.
A sample directory structure is available [here](https://git.xdrm.io/example/aicra/src/master/type.plugin).
##### 2. Generic driver
This is the same as with the plugin driver but instead of without `/main.go` at the end.
> Example - the `number` type checker will be inside `type/number` where **number** is an executable
A sample directory structure is available [here](https://git.xdrm.io/example/aicra/src/master/type.generic).
The programs will be given useful data (*i.e. method and arguments*) through its input arguments :
| Argument index | Description | Examble value |
| -------------- | ------------------------------------------------------------ | ------------------ |
| 1 | Uppercase method.<br>(_e.g. **$1** in bash, **argv[1]** in php_) | `MATCH` or `CHECK` |
| 2 | JSON representation of the input arguments.<br>(_e.g. **$2** in bash, **argv[2]** in php_) | ??? |
The standard output you will give back must be a `1` or `0` representing `true` and `false`.
+ When calling the `MATCH` method, the input argument consists of a string being the type checker name, you must return `1` this name is handled by the current type checker.
+ When calling the `CHECK` method, the input argument consists of a JSON representation wrapped inside the key `value`. For instance it could be `{"value": [1,2,3]}` if the input value is an array containing 1, 2, and 3.
### III. Build your project
After each controller, middle-ware or type checker implementation, you'll have to compile the project. This can be achieved through the command-line builder.
Usage is `aicra /path/to/your/project`.
Usually you just have to run the following command inside your project directory :
```bash
aicra .
```
The output should look like
![that](./README.assets/1531039386654.png).
#### IV. Main
The main default program is pretty small as shown below :
```go
package main
import (
"git.xdrm.io/go/aicra"
"net/http"
)
func main() {
// build from config
server, err := aicra.New("api.json")
if err != nil { panic(err) }
// launch server
err = http.ListenAndServe("127.0.0.1:4242", server)
if err != nil { panic(err) }
}
```
#### V. Change Log
### III/ Change Log
- [x] human-readable json configuration
- [x] nested routes (*i.e. `/user/:id:` and `/user/post/:id:`*)
@ -492,26 +198,18 @@ func main() {
- [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*)~~ Replaced by the middle-ware system
- [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*)
- [x] `int` - see go types
- [x] `uint` - see go types
- [x] `float` - see go types
- [x] `string` - any text
- [x] `varchar(min, max)` - any string with a length between `min` and `max`
- [ ] `<a>` - array containing **only** elements matching `a` type
- [ ] `<a:b>` - map containing **only** keys of type `a` and values of type `b` (*a or b can be ommited*)
- [x] `string(min, max)` - any string with a length between `min` and `max`
- [ ] `[a]` - array containing **only** elements matching `a` type
- [ ] `[a:b]` - 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
- [ ] ~~devmode watcher~~ : watch manifest, watch plugins to compile + hot reload them
- [x] driver for Go plugins
- [x] controllers
- [x] middlewares
- [x] type checkers
- [x] driver working with any executable through standard input and output
- [x] controllers
- [x] middlewares
- [x] type checkers
- [x] project configuration file to select **driver**, source folders and whether to load default type checkers.
- [x] used to compile the project by the `aicra` command
- [x] used to create an API from `aicra.New()`
- [ ] log bound resources when building the aicra server
- [ ] fail on check for unimplemented resources at server boot.
- [ ] fail on check for unavailable types in api.json at server boot.