Frontier

<p align=center> <img src="./docs/diagram/frontier-logo.png" width="30%"> </p> <div align="center">

English | 简体中文

</div>

Frontier is a full-duplex, open-source long-connection gateway written in Go. It enables microservices to directly reach edge nodes or clients, and vice versa. It provides full-duplex bidirectional RPC, messaging, and point-to-point streams. Frontier follows cloud-native architecture principles, supports fast cluster deployment via Operator, and is built for high availability and elastic scaling to millions of online edge nodes or clients.

Table of Contents

• Features
• Quick Start
• Architecture
• Usage
• Configuration
• Deployment
• Cluster
• Kubernetes
• Development
• Testing
• Community
• License

Quick Start

1. Run a single Frontier instance:

docker run -d --name frontier -p 30011:30011 -p 30012:30012 singchia/frontier:1.1.0

2. Build and run examples:

make examples

Run the chatroom example:

# Terminal 1
./bin/chatroom_service

# Terminal 2
./bin/chatroom_agent

Demo video:

https://github.com/singchia/frontier/assets/15531166/18b01d96-e30b-450f-9610-917d65259c30

Features

• Bidirectional RPC: Services and edges can call each other with load balancing.
• Messaging: Topic-based publish/receive between services, edges, and external MQ.
• Point-to-Point Streams: Open direct streams for proxying, file transfer, and custom traffic.
• Cloud-Native Deployment: Run via Docker, Compose, Helm, or Operator.
• High Availability and Scaling: Support for reconnect, clustering, and horizontal scale with Frontlas.
• Auth and Presence: Edge auth and online/offline notifications.
• Control Plane APIs: gRPC and REST APIs for querying and managing online nodes.

Architecture

Frontier Component

<img src="./docs/diagram/frontier.png" width="100%">

• Service End: The entry point for microservice functions, connecting by default.
• Edge End: The entry point for edge node or client functions.
• Publish/Receive: Publishing and receiving messages.
• Call/Register: Calling and registering functions.
• OpenStream/AcceptStream: Opening and accepting point-to-point streams (connections).
• External MQ: Frontier supports forwarding messages published from edge nodes to external MQ topics based on configuration.

Frontier requires both microservices and edge nodes to actively connect to Frontier. The metadata of Service and Edge (receiving topics, RPC, service names, etc.) can be carried during the connection. The default connection ports are:

• :30011: For microservices to connect and obtain Service.
• :30012: For edge nodes to connect and obtain Edge.
• :30010: For operations personnel or programs to use the control plane.

Functionality

<table><thead> <tr> <th>Function</th> <th>Initiator</th> <th>Receiver</th> <th>Method</th> <th>Routing Method</th> <th>Description</th> </tr></thead> <tbody> <tr> <td rowspan="2">Messager</td> <td>Service</td> <td>Edge</td> <td>Publish</td> <td>EdgeID+Topic</td> <td>Must publish to a specific EdgeID, the default topic is empty. The edge calls Receive to receive the message, and after processing, must call msg.Done() or msg.Error(err) to ensure message consistency.</td> </tr> <tr> <td>Edge</td> <td>Service or External MQ</td> <td>Publish</td> <td>Topic</td> <td>Must publish to a topic, and Frontier selects a specific Service or MQ based on the topic.</td> </tr> <tr> <td rowspan="2">RPCer</td> <td>Service</td> <td>Edge</td> <td>Call</td> <td>EdgeID+Method</td> <td>Must call a specific EdgeID, carrying the method name.</td> </tr> <tr> <td>Edge</td> <td>Service</td> <td>Call</td> <td>Method</td> <td>Must call a method, and Frontier selects a specific Service based on the method name.</td> </tr> <tr> <td rowspan="2">Multiplexer</td> <td>Service</td> <td>Edge</td> <td>OpenStream</td> <td>EdgeID</td> <td>Must open a stream to a specific EdgeID.</td> </tr> <tr> <td>Edge</td> <td>Service</td> <td>OpenStream</td> <td>ServiceName</td> <td>Must open a stream to a ServiceName, specified by service.OptionServiceName during Service initialization.</td> </tr> </tbody></table>

Key design principles include:

1. All messages, RPCs, and Streams are point-to-point transmissions.
   • From microservices to edges, the edge node ID must be specified.
   • From edges to microservices, Frontier routes based on Topic and Method, and finally selects a microservice or external MQ through hashing. The default is hashing based on edgeid, but you can choose random or srcip.
2. Messages require explicit acknowledgment by the receiver.
   • To ensure message delivery semantics, the receiver must call msg.Done() or msg.Error(err) to ensure delivery consistency.
3. Streams opened by the Multiplexer logically represent direct communication between microservices and edge nodes.
   • Once the other side receives the stream, all functionalities on this stream will directly reach the other side, bypassing Frontier's routing policies.

Usage

Detailed usage guide: docs/USAGE.md

Configuration

Detailed configuration guide: docs/CONFIGURATION.md

Deployment

In a single Frontier instance, you can choose the following methods to deploy your Frontier instance based on your environment.

Docker

docker run -d --name frontier -p 30011:30011 -p 30012:30012 singchia/frontier:1.1.0

Docker-Compose

git clone https://github.com/singchia/frontier.git
cd dist/compose
docker-compose up -d frontier

Helm

If you are in a Kubernetes environment, you can use Helm to quickly deploy an instance.

git clone https://github.com/singchia/frontier.git
cd dist/helm
helm install frontier ./ -f values.yaml

Your microservice should connect to service/frontier-servicebound-svc:30011, and your edge node can connect to the NodePort where :30012 is located.

Systemd

Use the dedicated Systemd docs:

dist/systemd/README.md

Operator

See the cluster deployment section below.

Cluster

Frontier + Frontlas Architecture

<img src="./docs/diagram/frontlas.png" width="100%">

The additional Frontlas component is used to build the cluster. Frontlas is also a stateless component and does not store other information in memory, so it requires additional dependency on Redis. You need to provide a Redis connection information to Frontlas, supporting redis, sentinel, and redis-cluster.

• Frontier: Communication component between microservices and edge data planes.
• Frontlas: Named Frontier Atlas, a cluster management component that records metadata and active information of microservices and edges in Redis.

Frontier needs to proactively connect to Frontlas to report its own, microservice, and edge active and status. The default ports for Frontlas are:

• :40011 for microservices connection, replacing the 30011 port in a single Frontier instance.
• :40012 for Frontier connection to report status.

You can deploy any number of Frontier instances as needed, and for Frontlas, deploying two instances separately can ensure HA (High Availability) since it does not store state and has no consistency issues.

Configuration

Frontier's frontier.yaml needs to add the following configuration:

frontlas:
  enable: true
  dial:
    network: tcp
    addr:
      - 127.0.0.1:40012
  metrics:
    enable: false
    interval: 0
daemon:
  # Unique ID within the Frontier cluster
  frontier_id: frontier01

Frontier needs to connect to Frontlas to report its own, microservice, and edge active and status.

Frontlas's frontlas.yaml minimal configuration:

control_plane:
  listen:
    # Microservices connect to this address to discover edges in the cluster
    network: tcp
    addr: 0.0.0.0:40011
frontier_plane:
  # Frontier connects to this address
  listen:
    network: tcp
    addr: 0.0.0.0:40012
  expiration:
    # Expiration time for microservice metadata in Redis
    service_meta: 30
    # Expiration time for edge metadata in Redis
    edge_meta: 30
redis:
  # Support for standalone, sentinel, and cluster connections
  mode: standalone
  standalone:
    network: tcp
    addr: redis:6379
    db: 0

Usage

Since Frontlas is used to discover available Frontiers, microservices need to adjust as follows:

Microservice Getting Service

package main

import (
  "net"
  "github.com/singchia/frontier/api/dataplane/v1/service"
)

func main() {
  // Use NewClusterService to get Service
  svc, err := service.NewClusterService("127.0.0.1:40011")
  // Start using service, everything else remains unchanged
}

Edge Node Getting Connection Address

For edge nodes, they still connect to Frontier but can get available Frontier addresses from Frontlas. Frontlas provides an interface to list Frontier instances:

curl -X GET http://127.0.0.1:40011/cluster/v1/frontiers

You can wrap this interface to provide