Concepts

httpin is driven by defining Go struct tags.

Let's take the following decleartion of a struct as an example to explain how it works:

type Authorization struct {
    Token string `in:"query=access_token,token;header=x-api-token;required"`
                      ^----------------------^ ^----------------^ ^------^
                                d1                    d2            d3
}

The key of the struct tag to drive httpin is in. Which is specific for the httpin package, like json for encoding/json.

We can define multiple directives in the tag, which must be separated by semicolons (;). See the example above, d1, d2, d3 are three different directives. httpin will run the directives in order (d1 -> d2 -> d3) for each corresponding struct field.

caution

Not every directive will be executed by httpin. It's decided by the executors (algorithms) of the directives and the actual input (request data).

The execution of a directive can fail, if a former directive failed, the latter ones won't be executed. If d1 failed, d2, d3 won't run.

Directive

Directive is a formatted string consisting of two parts, the directive executor, and the arguments, separated by an equal sign (=), formatted as:

name=argv

Which works like a function call.

The left to the = is the name of the directive. There's a corresponding directive executor (with the same name) working underhood.

The right to the = is the arguments, which will be passed to the algorithm at runtime. The way to define arguments can differ across different directives. In general, it will be a comma (,) separated strings for multiple arguments. Arguments can be ommited. For more specific usage, you should consult the documentation of the directives.

For the above example, there are three directives:

• d1: query=access_token,token
• d2: header=x-api-token
• d3: required

Let's dissect d1, i.e. query=access_token,token. The name is query. The argv is access_token,token. And after reading the documentation of query, we know the args will be treated as ["access_token", "token"].

Directive Executor

Directive Executor is an algorithm with runtime context who's responsible to execute a concrete directive.

To give a better understanding, we can treat Directive Executor as a function in a programming lanaguage, and treat Directive as a concrete function call.

e.g.

Diretive Executor	Directive	Execution
query	query=access_token,token	query(["access_token", "token"])
header	header=x-api-token,Authorization	header(["x-api-token", "Authorization"])
required	required	required([])