hiro
Hiro (snowcrash) is the Model Rocket project generation tool. Hiro borrows heavily
from go-swagger, but builds other custom components for projects
using the Model Rocket Cloud Core.
Install
Hiro uses go modules ensure the env var GO111MODULE=on
is set in your .bash_profile
or other appropriate location.
> go install gitlab.com/ModelRocket/hiro/cmd/hiro
Project Layout
All hiro projects have the same base layout:
~~~
├── .hiro // The hiro project dir
├── api/ // Generated API sources
│ └── api_name/ // The api name
│ └── rest/ // The swagger based rest api
| └── types/ // The api data types and models
| └── api_name.yaml // The swagger definition
├── functions/
│ └── .../ // Cloud functions
├── LICENSE // The project license
~~~
Getting started
You run hiro from with the directory you want to create a new project. This directory
must be within your $(GOPATH)/src. To initialize a project you simply point it at
your swagger document. This can be a file or a url, either will be copied to
api/swagger.yaml
Note: hiro cannot resolve private swagger documents at this time, so all definitions must
be public or contained within the same specification document. For projects that use domains
or external references, setup a GitHub sync in swagger to the git branch or the project
to the location above.
Initialize the project
> hiro init
Working with an API
Add an API
> hiro api add https://api.swaggerhub.com/apis/ModelRocket/acme/1.0.0/swagger.yaml
Sync the API
If you make changes to the API, you need to sync the swagger.
> hiro api sync
Create a cloud entry point for a specific API (lambda or otherwise)
> hiro function add acme
Run a function
hiro
will run any method and simulate an aws lambda proxy, or simply execute it with the specified environment.
Most commonly you want to build and run the function with API Gateway proxy support.
> hiro run --proxy=apigw --build ./functions/acme
Proxy Types
You use the proxy
parameter to tell hiro
how to handle the incoming data.
Proxy |
Description |
apigw * |
This will marshal incoming HTTP request into a events.APIGatewayProxyRequest object and return the expected result after unmarshaling from events.APIGatewayProxyResponse . |
raw |
This will pass the raw json event to the lambda handler as []byte. |
none |
This will not start a proxy, only execute the function and wait for it to complete. |
* apigw is the default proxy type. |
|
Environments
You can provide environment variables to a hiro function via the hiro.json
file.
{
"environment": {
"prod": {
"CLOUD_PROVIDER": "aws",
"DB_DRIVER": "postgres"
}
}
}
You can use this environment (the default is dev) by specifying in with run
> hiro run -e prod --proxy=apigw --build ./functions/acme
Docker
You can use the hiro docker in two ways.
Docker CLI
You can use it as a cli, but you need to share your local GOTPATH volume as well as set the working dir relative to the container volume. Keep in mind this is a very large image.
> docker run -v $GOPATH:/go -w /go/src/gitlab.com/decanter/decanter-api registry.gitlab.com/modelrocket/hiro/hiro-cli run --build ./functions/api
Hiro Container
You should use dep
to vendor your project first to ensure it can be built in a container.
The you can use the examples
as starting points for your apps.
Passing config to the container
When running your container you can pass the hiro config like this:
> docker run -v `pwd`:/config -e LOG_FORMAT=text -e LOG_LEVEL=debug -p 9000:9000 registry.gitlab.com/acme/acme-api:latest
This makes the current directory the /config
in the container and hiro will look for hiro.json
there.