113 lines
4.0 KiB
Markdown
113 lines
4.0 KiB
Markdown
# netcaptain
|
|
Sail the treacherous seas of the internet.
|
|
|
|
Netcaptain assists you in building and making HTTP requests.
|
|
|
|
## Vernacular:
|
|
### Quest - An internet adventure
|
|
Held in the `quests` directory under the given config directory, a quest will look something like this (we'll call this `quest` `auth`):
|
|
```
|
|
POST {{ .Crew.BaseURL }}/api/v1.0/auth
|
|
{"email":"{{.Args.Arg0}}","password":"{{.Args.Arg1}}"}
|
|
```
|
|
Or something like this (and this `quest` will be `lookup`):
|
|
```
|
|
Authorization: Bearer {{ .Hold.Token }}
|
|
GET http://192.168.86.197:8080/api/v1.0/lookup/book/{{ .Args.Arg0 }}
|
|
```
|
|
As you can see, support for `go` templates is built in. While executing the template, the captain will load as much information as can be loaded.
|
|
|
|
In the examples above we can see these variables:
|
|
* `.Crew.*`
|
|
* `.Hold.*`
|
|
* `.Args.Arg.*`
|
|
|
|
The `Crew` and the `Hold` are loaded if the captain is given a ship to sail. (A ship need not be specified if one named `default` exists in the given configuration.)
|
|
|
|
`Args` values are loaded at runtime by arguments passed on the command line in addition to the quest and ship.
|
|
|
|
That is:
|
|
`ncpt <quest> <ship> <Args.Arg0> <Args.Arg1> ...`
|
|
|
|
And for example:
|
|
`ncpt lookup enterprise Search+Term`
|
|
Will take the ship `enterprise` and go on the `lookup` quest providing:
|
|
* `Args.Arg0` = `Search+Term`
|
|
|
|
On the other hand, if `enterprise` is not the name of a defined ship, then you will go on the `lookup` quest providing:
|
|
* `Args.Arg0` = `enterprise`
|
|
* `Args.Arg1` = `Search+Term`
|
|
|
|
In this second case, if a `default` ship exists, it will be sailed, whether it contains anything to be used or not.
|
|
|
|
Quests can be easily edited in whatever editor you have defined in `EDITOR` by issuing:
|
|
`ncpt -e <quest>`
|
|
|
|
And quests can be validated (just run through the the parser without executing it) by issuing:
|
|
`ncpt -c <quest>`
|
|
|
|
And all available quests can be listed by issuing:
|
|
`ncpt -l`
|
|
|
|
### Ship - A Crew, and rules for Plunder and Delivery
|
|
Held in the `ships` directory under the given config directory, a ship will look something like this:
|
|
```
|
|
{
|
|
"crew": {
|
|
"BaseURL": "http://192.168.86.197:8080"
|
|
},
|
|
"plunder": {
|
|
"auth": {
|
|
"token": "token"
|
|
},
|
|
"ddg-search": {
|
|
"image": "Image",
|
|
"result": "Abstract"
|
|
}
|
|
}
|
|
}
|
|
```
|
|
Here we have a `Crew` some rules for `Plunder`, and a rule for `Deliver`.
|
|
|
|
The `Crew` is simple, we have a single Crew Member: `BaseURL`. Looking at the first Quest up above (`auth`):
|
|
```
|
|
POST {{ .Crew.BaseURL }}/api/v1.0/auth
|
|
{"email":"{{.Args.Arg0}}","password":"{{.Args.Arg1}}"}
|
|
```
|
|
So, when we pursue the `auth` quest using this `ship`, the `BaseURL` variable will be replaced with the given Crew member: `http://192.168.86.197:8080`)
|
|
|
|
The `Plunder` takes a little more explanation. Here we have defined a rule for plundering the `auth` `Quest`. It's basically saying "Upon completing the `auth` quest, I expect to receive `json` that contains, at the first level of the response, a `token` value. Store that value in the `Hold` under the name `token`."
|
|
|
|
The second `Plunder` rule will trigger on a Quest named `ddg-search`. It's going to pull a couple of values out of the top level of the response:
|
|
* `Image` stored in the ship `Hold` as `image` and
|
|
* `Abstract` stored in the ship `Hold` as `result`
|
|
|
|
Currently, only top-level values in JSON responses can be plundered.
|
|
|
|
Similarly to Quests, a Ship can easily be edited in whatever editor you have defined in EDITOR by issuing: ncpt -E <ship>
|
|
|
|
### Hold - Where Plunder is Stored
|
|
These are simple JSON files that act as key-value stores for anything plundered.
|
|
|
|
## Usage of ncpt:
|
|
```
|
|
Usage of ncpt:
|
|
-l List available Quests
|
|
-L List available Ships
|
|
-c <quest>
|
|
Validate that the given quest is _c_orrect
|
|
-C <ship>
|
|
Validate that the given ship is _C_orrect
|
|
-e <quest>
|
|
Edit the given quest
|
|
-E <ship>
|
|
Edit the given ship
|
|
-H <ship>
|
|
Edit the hold for the given ship
|
|
-h <ship> <key>
|
|
Output the value of <key> in the given ship's hold
|
|
-d string
|
|
The configuration directory to use (default ".ncpt")
|
|
-v Run in Verbose mode
|
|
```
|