microgateway

README

Microgateway Action for common microgateway patterns

Microgateway Action

This is a Microgateway Action which supports several common microgateway patterns , key ones highlighted below:

🔀 Conditional, content-based routing
🔐 JWT validation
⏳ Rate limiting
🔌 Circuit breaking

Quick Start

With Flogo CLI

The Flogo CLI takes a Flogo application defined in JSON and produces an executable application. The Flogo CLI can be installed from here. Next, follow the instructions here to build your first Microgateway Flogo application.

With Flogo API

The Flogo API allows developers to define Flogo applications in the Go programming language without using the Flogo CLI. You can get started by cloning this repo:

git clone https://github.com/project-flogo/microgateway.git

and then following the instructions here to build your first Microgateway Flogo application. Documentation for the Flogo Microgateway API can be found here.

Development

Testing

The commands supported include:

• clean
• build
• generate
• test
• test-short

To run tests issue the following command in the root of the project:

go run build/build.go test

It cleans the cache, and runs all the tests in your directory. The tests should take ~2 mintues. To re-run the tests first run the following:

To skip the integration tests use the test-short command:

go run build/build.go test-short

To know the USAGE and the list of commands supported:

go run build/build.go help

Resource

Schema

The JSON Schema for the Microgateway resource can be found here.

Sections

Services

A service defines a function or activity of some sort that will be utilized in a step within an execution flow. Services have names, refs, and settings. Any Flogo activity works as a service. Services that are specific to a microgateway can be found here. Services may call external endpoints like HTTP servers or may stay within the context of the gateway, like the js activity. Once a service is defined it can be used as many times as needed within your routes and steps.

A service definition looks like:

{
  "name": "PetStorePets",
  "description": "Get pets by ID from the petstore",
  "ref": "github.com/project-flogo/contrib/activity/rest",
  "settings": {
    "uri": "http://petstore.swagger.io/v2/pet/:petId",
    "method": "GET"
  }
}

Steps

Each microgateway is composed of a number of steps. Each step is evaluated in the order in which it is defined via an optional if condition. If the condition is true, that step is executed. If that condition is false the execution context moves onto the next step in the process and evaluates that one. A blank or omitted if condition always evaluates to true.

A simple step looks like:

{
  "if": "$.payload.pathParams.petId == 9",
  "service": "PetStorePets",
  "input": {
    "method": "GET",
    "pathParams.id": "=$payload.pathParams.petId"
  }
}

As you can see above, a step consists of a simple condition, a service reference, input parameters, and (not shown) output parameters. The service must map to a service defined in the services array that is defined in the microgateway resource. Input key and value pairs are translated and handed off to the service execution. Output key value pairs are translated and retained after the service has executed. Values starting with = are evaluated as variables within the context of the execution. An optional halt condition is supported for steps. When the halt condition is true the execution of the steps is halted.

Responses

Each microgateway has an optional set of responses that can be evaluated and returned to the invoking trigger. Much like routes, the first response with an if condition evaluating to true is the response that gets executed and returned. A response contains an if condition, an error boolean, a code value, and a data object. The error boolean dictates whether or not an error should be returned to the engine. The code is the status code returned to the trigger. The data object is evaluated within the context of the execution and then sent back to the trigger as well.

A simple response looks like:

{
  "if": "$.PetStorePets.outputs.data.status == 'available'",
  "error": false,
  "code": 200,
  "data": {
    "body.pet": "=$.PetStorePets.outputs.data",
    "body.inventory": "=$.PetStoreInventory.outputs.data"
  }
}

Example Flogo JSON Usage of a Microgateway Action

An example of a basic gateway can be found here.

Example Flogo API Usage of a Microgateway Action

An API example can be found here.

Documentation

Index

• Constants
• func Generate(config *app.Config, file string, modFile string)
• func Load(pattern string) (*api.Microgateway, error)
• func Register(patternName string, pattern string) error
• type Action
  • func (a *Action) IOMetadata() *metadata.IOMetadata
  • func (a *Action) Metadata() *action.Metadata
  • func (a *Action) Run(ctx context.Context, input map[string]interface{}) (map[string]interface{}, error)
• type Factory
  • func (f *Factory) Generate(settingsName string, imports *Imports, config *action.Config) (code string, err error)
  • func (f *Factory) Initialize(ctx action.InitContext) error
  • func (f *Factory) New(config *action.Config) (action.Action, error)
• type GenerateResource
• type Generator
• type Import
  • func (i *Import) GetAlias() string
• type Imports
  • func (i *Imports) Ensure(path string, options ...string) *Import
• type Input
  • func (r *Input) FromMap(values map[string]interface{}) error
  • func (r *Input) ToMap() map[string]interface{}
• type Manager
  • func (m *Manager) Generate() bool
  • func (m *Manager) LoadResource(config *resource.Config) (*resource.Resource, error)
• type Output
  • func (o *Output) FromMap(values map[string]interface{}) error
  • func (o *Output) ToMap() map[string]interface{}
• type Settings

Constants

const VersionMaster = "master"

VersionMaster is the master version

Functions

func Generate

func Generate(config *app.Config, file string, modFile string)

Generate generates flogo go API code

func Load

func Load(pattern string) (*api.Microgateway, error)

Load loads a pattern

func Register

func Register(patternName string, pattern string) error

Registers a pattern

Types

type Action

type Action struct {
	// contains filtered or unexported fields
}

Action is the microgateway action

func (*Action) IOMetadata

func (a *Action) IOMetadata() *metadata.IOMetadata

IOMetadata returns the iometadata for the microgateway

func (*Action) Metadata

func (a *Action) Metadata() *action.Metadata

Metadata returns the metadata for the microgateway

func (*Action) Run

func (a *Action) Run(ctx context.Context, input map[string]interface{}) (map[string]interface{}, error)

Run executes the microgateway

type Factory

type Factory struct {
	*resource.Manager
	// contains filtered or unexported fields
}

Factory is a microgateway factory

func (*Factory) Generate

func (f *Factory) Generate(settingsName string, imports *Imports, config *action.Config) (code string, err error)

Generate generates go code from an action

func (*Factory) Initialize

func (f *Factory) Initialize(ctx action.InitContext) error

Initialize initializes the factory

func (*Factory) New

func (f *Factory) New(config *action.Config) (action.Action, error)

New creates a new microgateway

type GenerateResource

type GenerateResource interface {
	Generate() bool
}

GenerateResource is used to determine if a resource is generated, defaults to true

type Generator

type Generator interface {
	Generate(settingsName string, imports *Imports, config *action.Config) (code string, err error)
}

Generator generates code for an action

type Import

type Import struct {
	Alias   string
	Import  string
	Version string
	Port    string
	Used    bool
}

Import is a package import

func (*Import) GetAlias

func (i *Import) GetAlias() string

GetAlias gets the import alias and marks it as used

type Imports

type Imports struct {
	Imports []*Import
}

Imports are the package imports

func (*Imports) Ensure

func (i *Imports) Ensure(path string, options ...string) *Import

Ensure looks up an import and adds it if it is missing

type Input

type Input struct {
}

Input represents the inputs into the microgateway

func (*Input) FromMap

func (r *Input) FromMap(values map[string]interface{}) error

FromMap sets Input from a map

func (*Input) ToMap

func (r *Input) ToMap() map[string]interface{}

ToMap converts Input to a map

type Manager

type Manager struct {
}

Manager loads the microgateway definition resource

func (*Manager) Generate

func (m *Manager) Generate() bool

Generate disables generation of the microgateway resource type

func (*Manager) LoadResource

func (m *Manager) LoadResource(config *resource.Config) (*resource.Resource, error)

LoadResource loads the microgateway definition

type Output

type Output struct {
}

Output represents the outputs from the microgateway

func (*Output) FromMap

func (o *Output) FromMap(values map[string]interface{}) error

FromMap sets Output from a map

func (*Output) ToMap

func (o *Output) ToMap() map[string]interface{}

ToMap converts Output to a map

type Settings

type Settings struct {
	URI   string `md:"uri,required"`
	Async bool   `md:"async"`
}

Settings are the settings for the microgateway