English | 简体中文
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.
- Features
- Quick Start
- Architecture
- Usage
- Configuration
- Deployment
- Cluster
- Kubernetes
- Development
- Testing
- Community
- License
- Run a single Frontier instance:
docker run -d --name frontier -p 30011:30011 -p 30012:30012 singchia/frontier:1.1.0- Build and run examples:
make examplesRun the chatroom example:
# Terminal 1
./bin/chatroom_service
# Terminal 2
./bin/chatroom_agentDemo video:
chatroom-min.mov
- 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.
Frontier Component
- 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.
| Function | Initiator | Receiver | Method | Routing Method | Description |
|---|---|---|---|---|---|
| Messager | Service | Edge | Publish | EdgeID+Topic | 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. |
| Edge | Service or External MQ | Publish | Topic | Must publish to a topic, and Frontier selects a specific Service or MQ based on the topic. | |
| RPCer | Service | Edge | Call | EdgeID+Method | Must call a specific EdgeID, carrying the method name. |
| Edge | Service | Call | Method | Must call a method, and Frontier selects a specific Service based on the method name. | |
| Multiplexer | Service | Edge | OpenStream | EdgeID | Must open a stream to a specific EdgeID. |
| Edge | Service | OpenStream | ServiceName | Must open a stream to a ServiceName, specified by service.OptionServiceName during Service initialization. |
Key design principles include:
- 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.
- 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.
- 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.
Detailed usage guide: docs/USAGE.md
Detailed configuration guide: docs/CONFIGURATION.md
In a single Frontier instance, you can choose the following methods to deploy your Frontier instance based on your environment.
docker run -d --name frontier -p 30011:30011 -p 30012:30012 singchia/frontier:1.1.0git clone https://github.com/singchia/frontier.git
cd dist/compose
docker-compose up -d frontierIf 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.yamlYour microservice should connect to service/frontier-servicebound-svc:30011, and your edge node can connect to the NodePort where :30012 is located.
Use the dedicated Systemd docs:
See the cluster deployment section below.
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:
:40011for microservices connection, replacing the 30011 port in a single Frontier instance.:40012for 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.
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: frontier01Frontier 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: 0Since 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/frontiersYou can wrap this interface to provide load balancing or high availability for edge nodes, or add mTLS to directly provide to edge nodes (not recommended).
Control Plane gRPC See Protobuf Definition.
The Frontlas control plane differs from Frontier as it is a cluster-oriented control plane, currently providing only read interfaces for the cluster.
service ClusterService {
rpc GetFrontierByEdge(GetFrontierByEdgeIDRequest) returns (GetFrontierByEdgeIDResponse);
rpc ListFrontiers(ListFrontiersRequest) returns (ListFrontiersResponse);
rpc ListEdges(ListEdgesRequest) returns (ListEdgesResponse);
rpc GetEdgeByID(GetEdgeByIDRequest) returns (GetEdgeByIDResponse);
rpc GetEdgesCount(GetEdgesCountRequest) returns (GetEdgesCountResponse);
rpc ListServices(ListServicesRequest) returns (ListServicesResponse);
rpc GetServiceByID(GetServiceByIDRequest) returns (GetServiceByIDResponse);
rpc GetServicesCount(GetServicesCountRequest) returns (GetServicesCountResponse);
}Install CRD and Operator
Follow these steps to install and deploy the Operator to your .kubeconfig environment:
git clone https://github.com/singchia/frontier.git
cd dist/crd
kubectl apply -f install.yamlCheck CRD:
kubectl get crd frontierclusters.frontier.singchia.ioCheck Operator:
kubectl get all -n frontier-systemFrontierCluster
apiVersion: frontier.singchia.io/v1alpha1
kind: FrontierCluster
metadata:
labels:
app.kubernetes.io/name: frontiercluster
app.kubernetes.io/managed-by: kustomize
name: frontiercluster
spec:
frontier:
# Single instance Frontier
replicas: 2
# Microservice side port
servicebound:
port: 30011
# Edge node side port
edgebound:
port: 30012
frontlas:
# Single instance Frontlas
replicas: 1
# Control plane port
controlplane:
port: 40011
redis:
# Dependent Redis configuration
addrs:
- rfs-redisfailover:26379
password: your-password
masterName: mymaster
redisType: sentinelSave asfrontiercluster.yaml，and
kubectl apply -f frontiercluster.yaml
In 1 minute, you will have a 2-instance Frontier + 1-instance Frontlas cluster.
Check resource deployment status with:
kubectl get all -l app=frontiercluster-frontier
kubectl get all -l app=frontiercluster-frontlasNAME READY STATUS RESTARTS AGE
pod/frontiercluster-frontier-57d565c89-dn6n8 1/1 Running 0 7m22s
pod/frontiercluster-frontier-57d565c89-nmwmt 1/1 Running 0 7m22s
NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE
service/frontiercluster-edgebound-svc NodePort 10.233.23.174 <none> 30012:30012/TCP 8m7s
service/frontiercluster-servicebound-svc ClusterIP 10.233.29.156 <none> 30011/TCP 8m7s
NAME READY UP-TO-DATE AVAILABLE AGE
deployment.apps/frontiercluster-frontier 2/2 2 2 7m22s
NAME DESIRED CURRENT READY AGE
replicaset.apps/frontiercluster-frontier-57d565c89 2 2 2 7m22s
NAME READY STATUS RESTARTS AGE
pod/frontiercluster-frontlas-85c4fb6d9b-5clkh 1/1 Running 0 8m11s
NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE
service/frontiercluster-frontlas-svc ClusterIP 10.233.0.23 <none> 40011/TCP,40012/TCP 8m11s
NAME READY UP-TO-DATE AVAILABLE AGE
deployment.apps/frontiercluster-frontlas 1/1 1 1 8m11s
NAME DESIRED CURRENT READY AGE
replicaset.apps/frontiercluster-frontlas-85c4fb6d9b 1 1 1 8m11s
Your microservice should connect to service/frontiercluster-frontlas-svc:40011, and your edge node can connect to the NodePort where :30012 is located.
See ROADMAP
If you find any bugs, please open an issue, and project maintainers will respond promptly.
If you wish to submit features or more quickly address project issues, you are welcome to submit PRs under these simple conditions:
- Code style remains consistent
- Each submission includes one feature
- Submitted code includes unit tests
Join our WeChat group for discussions and support.
Released under the Apache License 2.0
A Star ⭐️ would be greatly appreciated