README.md

Project Flogo is an Open Source ecosystem for event-driven apps

Ecosystem | Repos | Core | Flows | Streams | Flogo Rules | Go Developers | When to use Flogo | Contributing | License

Project Flogo is an ultra-light, Go-based open source ecosystem for building event-driven apps. Event-driven, you say? Yup, the notion of triggers and actions are leveraged to process incoming events. An action, a common interface, exposes key capabilities such as application integration, stream processing, etc.

• App = Trigger(s) + Actions[&Activities]
• Triggers
  • receive data from external sources.
  • are managed by a configurable threading model
  • have a common interface enabling anyone to build a Flogo trigger.
• Handlers
  • dispatch events to actions
• Actions
  • process events in a manner suitable with the implementation
  • have a common interface enabling opinionated event processing capabilities

Project Flogo Ecosystem

All capabilities within the Flogo Ecosystem have a few things in common, they all process events (in a manner suitable for the specific purpose) and they all implement the action interface exposed by Flogo Core.

Some of the key highlights include:

🎈 Ultra-light 20x-50x lighter than Java or Node.js
⚡️ Event-driven Powerful event-driven programming model based on triggers and actions
⚙️ Common core a single, common core enables reuse and flexibility across all eventing constructs
✏️ Golang based Written entirely in Golang for efficiency
💪 Deployment flexibility Deploy as ultra-lightweight serverless functions, containers or static binaries on IoT edge devices
🧠 Native machine learning Purpose built activity for TensorFlow SavedModel inferencing
😍 100% Open Source for your dev & hacking pleasure

• Integration Flows Application Integration process engine with conditional branching and a visual development environment
  
• Stream Processing a simple pipeline-based stream processing action with event joining capabilities across multiple triggers & aggregation over time windows
  
• Contextual Decisioning Declarative Rules for Real-time Contextual Decisions
  
• Microgateway Microgateway pattern for conditional, content-based routing, JWT validation, rate limiting, circuit breaking and other common patterns
  

The concept is simple, an event is just that, an event, how it’s processed is what differs. Flogo Core eases the burden by enabling a common set of functionality, such as:

• threading
• logging
• data type coercion
• data mapping
• tracing & monitoring hooks

While also exposing a common set of contributions via activities and triggers. For example, all available triggers can be leveraged to dispatch events to any action implementation, that is, flows for application integration, streams for stream processing, rules for contextual rule processing, etc.

Flogo Repos

Project Flogo consists of the following sub-projects available as separate repos under a seperated GitHub Org:

• project-flogo/flogo-cli: Command line tools for building Flogo apps & extensions
• project-flogo/flogo-core: The core Flogo library
• project-flogo/flogo-contrib: Flogo contributions/extensions
• project-flogo/stream: Flogo Streams Action
• project-flogo/rules: Contextual, deterministic rules action
• project-flogo/microgateway: Flogo Microgateway Action
• project-flogo/flogo-web: Flogo Web UI

Flogo Core

Flogo Core is an event-driven app framework used to develop apps for the cloud & IoT edge. It can also be thought of as a lightweight app kernel used by open source & commercial solutions.

Flogo Core provides the following key benefits:

⛓ Action chaining enables communication between one or more capabilities in a single, sub 10MB binary!
🏗 Common contribution model build activities and triggers that can be leveraged by all capabilities
🔨 Extensible easily extend the capabilities available by building your own action using the common interfaces

Flogo Core Contribution Model

Flogo Core exposes three principal contribution interfaces that enable developers to build common capabilities and functionality. These contribution interfaces include:

• Trigger Interface a common interface for building event-consumers that dispatch events to one or more actions. The Kafka subscriber is an example of a trigger.
• Activity Interface a common interface for exposing common application logic in a reusable manner. Think of this as a function, such as write to database, publish to Kafka, etc that can be used by all Flogo apps.
• Action Interface a common interface for processing events. Actions contain the specific capability logic, such as integration, stream processing, rule processing, etc. Actions have a great deal of flexibility in how they’re developed and how developers leverage actions within their overall applications. For example, flows and streams expose JSON-based DSLs & Go APIs for maximum developer flexibility.

Flogo Flows

Flogo Flows provides application integration capabilities and includes the following key highlights.

🌈 Painless development Visual modeler with step-back debugging capabilities & elegant DSL
⚙️ Ultra-light process engine for conditional flow control

Getting Started

We've made getting started with Flogo Flows as easy as possible. The current set of tooling is designed for:

• Serverless function developers
• Cloud-native microservices developers
• IoT Solutions developers
• Go Developers

Zero-code Developers

If your background is in or you prefer to develop your apps using zero-coding environments, then read on, because we’ve got something special for you.

Flows Web UI is available via Docker Hub or Flogo.io. The Docker image contains the Flows Web UI along with all required components to begin developing, testing and building deployable artifacts right from your web browser.

To report any issues with the Issue tracker on this project.

Flogo Streams

Edge devices have the potential for producing millions or even billions of events at rapid intervals, often times the events on their own are meaningless, hence the need to provide basic streaming operations against the slew of events.

A native streaming action as part of the Project Flogo Ecosystem accomplishes the following primary objectives:

• Enables apps to implement basic streaming constructs in a simple pipeline fashion
• Provides non-persistent state for streaming operations
  • Streams are persisted in memory until the end of the pipeline
• Serves as a pre-process pipeline for raw data to perform basic mathematical and logical operations. Ideal for feeding ML models

Some of the key highlights include:

😀 Simple pipeline construct enables a clean, easy way of dealing with streams of data
⏳ Stream aggregation across streams using time or event tumbling & sliding windows
🙌 Join streams from multiple event sources
🌪 Filter out the noise with stream filtering capabilities

Getting Started

We’ve made building powerful streaming pipelines as easy as possible. Develop your pipelines using:

• A simple, clean JSON-based DSL
• Golang API

See the sample below of an aggregation pipeline (for brevity, the triggers and metadata of the resource has been omitted). Also don’t forget to check out the examples in the project-flogo/stream repo.

  "stages": [
    {
      "ref": "github.com/project-flogo/stream/activity/aggregate",
      "settings": {
        "function": "sum",
        "windowType": "timeTumbling",
        "windowSize": "5000"
      },
      "input": {
        "value": "=$.input"
      }
    },
    {
      "ref": "github.com/project-flogo/contrib/activity/log",
      "input": {
        "message": "=$.result"
      }
    }
  ]

Flogo Rules

Processing Events in real-time to determine next best action is an important function of Event driven applications. With the vast amount of events that are generated from different sources, making sense of the information in a given context can be immensely valuable.

Flogo Rules simplifies the complexity involved with real-time contextual decisions.

Flogo Rules supports

• Declarative Rules to define conditional logic and trigger result rules
• Joins/Correlations across multiple Event sources
• Ability to define Rule Priorities
• Timer Events; Configurable TTL (time to live) -1 - no expiry, 0 - event expiry set to end of run to completion cycle.
• Forward chaining for Inferencing

The CLI

The CLI is used to build all applications that leverage the JSON-based DSL. If you’re using the Go API to build your apps, feel free to just go build your stuff without the flogo CLI.

Getting started with the CLI couldn't be any easier (refer to Flogo CLI repo for detail instructions and dependencies):

• Install the CLI

go install github.com/project-flogo/cli/...@latest

• Create & build your app

• flogo the core CLI for creating and building your applications
• flogogen a scaffolding tool to begin building your Flogo contributions (activities, triggers & actions)

If you're interested in building your own contribution(s), refer to the Flogo Documentation or join us on the project-flogo/Lobby Gitter Channel.

Golang API

Are you the kind of person who would rather code, but would love to leverage the capabilities of the Flogo Ecosystem? Makes total sense, we just ❤️ to code also! We’ve exposed a number of Go APIs for leveraging the various action types, activities and triggers. Getting started is pretty easy, just follow the steps below.

• Create your new project dir and init your module

mkdir test
cd test
go mod init example.com/m

• Go get the latest flogo core

go get github.com/project-flogo/core

• Optionally, if you're using any of the Flogo contributions, don't forget to get that repo, as well

go get github.com/project-flogo/contrib

• Open up your favorite IDE or txt editor and start coding!

package main

import (
	"context"
	"fmt"

	"github.com/project-flogo/contrib/activity/log"
	"github.com/project-flogo/contrib/trigger/rest"
	"github.com/project-flogo/core/activity"
	"github.com/project-flogo/core/api"
	"github.com/project-flogo/core/data/coerce"
	"github.com/project-flogo/core/engine"
)

func main() {

	app := myApp()

	e, err := api.NewEngine(app)

	if err != nil {
		fmt.Println("Error:", err)
		return
	}

	engine.RunEngine(e)
}

func myApp() *api.App {
	app := api.NewApp()

	trg := app.NewTrigger(&rest.Trigger{}, &rest.Settings{Port: 8080})
	h, _ := trg.NewHandler(&rest.HandlerSettings{Method: "GET", Path: "/blah/:num"})
	h.NewAction(RunActivities)

	//store in map to avoid activity instance recreation
	logAct, _ := api.NewActivity(&log.Activity{})
	activities = map[string]activity.Activity{"log": logAct}

	return app
}

var activities map[string]activity.Activity

func RunActivities(ctx context.Context, inputs map[string]interface{}) (map[string]interface{}, error) {

	trgOut := &rest.Output{}
	trgOut.FromMap(inputs)

	msg, _ := coerce.ToString(trgOut.PathParams)
	_, err := api.EvalActivity(activities["log"], &log.Input{Message: msg})
	if err != nil {
		return nil, err
	}

	response := make(map[string]interface{})

	response["id"] = "123"
	response["amount"] = "1"
	response["balance"] = "500"
	response["currency"] = "USD"

	reply := &rest.Reply{Code: 200, Data: response}
	return reply.ToMap(), nil
}

• Don't forget to tidy your dependencies

go mod tidy

• Before we can build the app, let's generate the metadata for the triggers

go generate

• Build the app

go build

When to use Flogo

You’ll look to leverage Flogo if you’re a dev & sick of building all the messy stuff that comes along with coding production apps. Such as connectivity to event-driven messaging platforms, datastores, SaaS apps, etc & want to deploy to a wide range of targets, such as

• serverless compute
• IoT edge devices
• containers

The broader Flogo ecosystem exposes an opinionated perspective on building event-driven apps. If you’re looking to process events in any of the following ways, then read on because the Project Flogo Ecosystem is for you!

• long running processes with flow-control support geared toward application integration
• consuming and manipulating large streams of events via a pipeline to act as a pre-processor for time-series data to serve things like machine learning models or to derive simple conclustions via data aggregation
• contextual, declarative rules for real-time decisioning

In short...

Flogo is...	Flogo is not...
an ecosystem of opinionated, event-driven capabilities	a front-end web app or analytics framework
a Go lib to increase dev productivity	an IoT platform

Contributing

Want to contribute to Project Flogo? We've made it easy, all you need to do is fork the repository you intend to contribute to, make your changes and create a Pull Request! Once the pull request has been created, you'll be prompted to sign the CLA (Contributor License Agreement) online.

Not sure where to start? No problem, here are a few suggestions:

• flogo-contrib: This repository contains all of the standard contributions, such as activities, triggers, etc. Perhaps there is something missing? Create a new activity or trigger or fix a bug in an existing activity or trigger. Don't forget to check all of the other repositores in the project-flogo org on GitHub, as some contributions are large enough to have their own repo.
• Browse all of the [Project Flogo repositories] and look for issues tagged kind/help-wanted or good first issue

If you have any questions, feel free to post an issue and tag it as a question, email [email protected] or chat with the team and community:

• The project-flogo/Lobby Gitter channel should be used for general discussions, start here for all things Flogo!
• The project-flogo/developers Gitter channel should be used for developer/contributor focused conversations.

For additional details, refer to the Contribution Guidelines.

License

Project Flogo is licensed under a BSD-style license. Refer to LICENSE for license text.

Usage Guidelines

We’re excited that you’re using Project Flogo to power your project(s). Please adhere to the usage guidelines when referencing the use of Project Flogo within your project(s) and don't forget to let others know you're using Project Flogo by proudly displaying one of the following badges or the Flynn logo, found in the branding folder of this project.