go/aicra
go
/
aicra
0
1
Fork 0
Code Issues Pull Requests Releases 3 Wiki Activity

update readme to drivers, etc

This commit is contained in:
Adrien Marquès 2018-10-01 21:11:11 +02:00
parent d406338777
commit b02dc60b3d
2 changed files with 141 additions and 42 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

BIN
README.assets/1531039386654.png
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 46 KiB

After

Width:  |  Height:  |  Size: 63 KiB

183
README.md
View File

@ -8,6 +8,14 @@
**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 through middlewares, file upload, rich argument parsing (*i.e. url slash-separated, urlencoded, form-data, json*), nested routes, project compiler (*i.e. aicra*), etc. **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 through middlewares, file upload, rich argument parsing (*i.e. url slash-separated, urlencoded, form-data, json*), nested routes, project compiler (*i.e. aicra*), etc.
All the REST API management is done for you, you just need to implement :
- the controllers
- the middlewares (to manage authentication, csrf, etc)
- the type checkers to check if input arguments follows some rules
There is 2 drivers that lets you implement these features in Go or whatever language.
This framework is based over some of the following concepts. This framework is based over some of the following concepts.
@ -15,7 +23,7 @@ This framework is based over some of the following concepts.
| concept | explanation | | concept | explanation |
|---|---| |---|---|
| meaningful defaults | Defaults and default values work without further understanding | | 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. | | configuration driven | Avoid information duplication. Automate anything that can be automated without losing control. Have *one* configuration that summarizes the whole project, its behavior and its automation flow. |
> A working example is available [here](https://git.xdrm.io/example/aicra) > A working example is available [here](https://git.xdrm.io/example/aicra)
@ -56,9 +64,9 @@ It should now be available locally and available for your imports.
##### 2. Compile the command-line builder ##### 2. Compile the command-line compiler
You should then compile the project builder to help you manage your projects. You should then compile the project compiler to help you manage your projects.
```bash ```bash
go install git.xdrm.io/go/aicra/cmd/aicra go install git.xdrm.io/go/aicra/cmd/aicra
@ -74,84 +82,164 @@ go install git.xdrm.io/go/aicra/cmd/aicra
The default project structure for **aicra** is as follows : The default project structure for **aicra** is as follows :
``` ```
├── main.go - the entry point ├── main.go - entry point
├── manifest.json - the configuration file |
├── aicra.json - server configuration file
├── api.json - API configuration file
|
├── middleware - middleware implementations ├── middleware - middleware implementations
├── controller - controller implementations ├── controller - controller implementations
└── types - custom type for the type checker └── type - custom type checkers
``` ```
In order for your project to be run, each controller, middleware and type checker has to be compiled as a *plugin* (*i.e. shared objects*). They can then be loaded by the server.
##### 1. Compilation configuration
The `aicra.json` configuration file defines where are located your controllers, type checkers, and middlewares ; also it contains what driver you want to use, you have 2 choices :
1. **plugin** - for Go implementations
2. **generic** - for any language implementation (uses standard input and output)
| field | description | example value |
| ------------------ | ------------------------------------------------------------ | -------------------- |
| root | The project folder path | `./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`, `false` |
| types.folder | The folder (relative to the project root) where type checkers' implementations are located | `./type` |
| controllers.folder | The folder (relative to the project root) where controllers' implementations are located | `./controller` |
| middlewares.folder | The folder (relative to the project root) where middlewares' implementations are located | `./middleware` |
A sample file can be found [here](https://git.xdrm.io/example/aicra/src/master/aicra.json).
##### 1. Configuration ##### 2. API Configuration
The whole project behavior is described inside the `manifest.json` file. For a better understanding of the format, take a look at this working [template](https://git.xdrm.io/example/aicra/src/master/manifest.json). This file contains information about : 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 :
- resources routes and their methods - resource routes and their methods
- every input for each method (called *argument*) - every input for each method (called *argument*)
- every output for each method - every output for each method
- scope permissions - scope permissions (list of permissions you can compose)
- input policy : type, required/optional, default value, variable renaming, etc. - input policy :
- type of argument
- required/optional
- default value
- variable renaming
##### 2. Controllers ##### 3. Controllers
For each route, you'll have to place your implementation into the `controller` folder following the naming convention : add `/main.go` at the end of the route. Controllers implement `Get`, `Post`, `Put`, and `Delete` methods, and have access to special variables surrounded by underscores :
> Example - `/path/to/some/uri` will be inside `controller/path/to/some/uri/main.go`. - `_HTTP_METHOD_` the request's HTTP method in uppercase
- `_SCOPE_` the scope filled by middlewares
A sample directory structure is available [here](https://git.xdrm.io/example/aicra/src/master/controller). - `_AUTHORIZATION_` the request's **Authorization** header
##### 3. Middlewares Also special variables found in the return data are processed with special actions :
In order for your project to manage authentication, the best solution is to create middlewares, there are programs that updates a *Scope* 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 scope are used to match the `scope` field in the configuration file and automatically block non-authenticated requests. Scopes can also be used for implementation-specific behavior. - `_REDIRECT_` will redirect to the URL contained in the variable
Each middleware must be directly inside the `middleware` folder. ###### 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> - `/path/to/some/uri` will be inside `controller/path/to/some/uri/main.go`
> <u>Exception</u> - `/` will be inside `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 `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.
###### Generic driver
This is the same as with the plugin driver but instead of without `/main.go` at the end.
> <u>Example</u> - `/path/to/some/uri` will be inside `controller/path/to/some/uri` where the **uri** file is an executable.
> <u>Exception</u> - `/` will be inside `controller/ROOT`.
A sample directory structure is available [here](https://git.xdrm.io/example/aicra/src/master/controller.generic).
##### 4. Middlewares
In order for your project to manage authentication, the best solution is to create middlewares, 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 scope are used to match the `scope` field in the configuration file and automatically block non-authenticated requests. Scopes can also be used for implementation-specific behavior such as _CSRF_ management. Controllers have access to the scope through the variable `_SCOPE_`.
###### 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`. > Example - the `1-authentication` middleware will be inside `middleware/1-authentication/main.go`.
**Note** - middleware execution will be ordered by name. Prefixing your middlewares with their order is a good practice. **Note** - middleware execution will be ordered by name. Prefixing your middlewares with their order is a good practice.
A sample directory structure is available [here](https://git.xdrm.io/example/aicra/src/master/middleware.plugin).
##### 4. Custom types
In your configuration you will have to use built-in types (*e.g.* int, any, varchar), 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).
Each type must be inside a unique package 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 matches the name. Each middleware must implement the `git.xdrm.io/go/aicra/driver.Middleware` interface. In addition you must declare the function `func Export() Middleware` to allow dynamic loading of your middleware.
###### Generic driver
This is the same as with the plugin driver but instead of without `/main.go` at the end.
> Example - the `1-authentication` middleware 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).
##### 5. Custom types
In your configuration you will have to use built-in types (*e.g.* int, any, varchar), 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 matches the name.
###### 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).
###### 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).
#### III. Build your project #### III. Build your project
After each controller, middleware or type edition, you'll have to rebuild the project. This can be achieved through the command-line builder. After each controller, middleware or type implementation, you'll have to compile the project. This can be achieved through the command-line builder.
Usage is `aicra [options] /path/to/your/project`. Usage is `aicra /path/to/your/project`.
Options:
- `-c` - overrides the default controllers path ; default is `./controller`
- `-m` - overrides the default middlewares path ; default is `./middleware`
- `-t` - overrides the default custom types path ; default is `./custom-types`
For a project that does not need a different structure, you just have to run this command under your project root Usually you just have to run the following command inside your project directory :
```bash ```bash
aicra . aicra .
@ -175,8 +263,8 @@ import (
func main() { func main() {
// 1. create server // 1. create the API from the configuration file
server, err := aicra.New("manifest.json") server, err := aicra.New("api.json")
if err != nil { if err != nil {
panic(err) panic(err)
} }
@ -217,3 +305,14 @@ func main() {
- [x] generic controllers implementation (shared objects) - [x] generic controllers implementation (shared objects)
- [x] response interface - [x] response interface
- [ ] devmode watcher : watch manifest, watch plugins to compile + hot reload them - [ ] 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()`