gate

README

gate

The gate is an API Gateway.

Supported Protocols

• HTTP
• WebSocket

Features

• Translate HTTP round-trip to RPC to backend micro-services.
• Translate WebSocket to bidirectional streaming RPC to backend services.
• JSON payload is sent to and recv from backend services as it is.
• Backend services are discovered by service name and selected evenly across multiple instances.
• Built-in observability of metrics and tracing.
• Provides utilities such as image placeholder and file uploader out of box.
• HTTP paths are dynamically mapped to services by the resolver as below.

API Resolver

gate dynamically routes to services using a namespace value and the HTTP path. If a service have a name (io.goeasy.service.comet) and a method (Comet.Subscribe), let's first define some concepts:

io.goeasy.service.comet/Comet.Subscribe
<---1---> <--2--> <-3-> <------5------>
<----------4---------->

• Part 1 is a namespace
• Part 2 is a type
• Part 3 is an alias, or short name
• Altogether they compose part 4, which is FQDN, the global unique service name
• Part 5 is a method or endpoint

URLs are resolved as follows:

Path	Service	Method
/foo/bar	io.goeasy.service.foo	Foo.Bar
/foo/bar/baz	io.goeasy.service.foo	Bar.Baz
/foo/bar/baz/cat	io.goeasy.service.foo.bar	Baz.Cat

Versioned API URLs can easily be mapped to service names:

Path	Service	Method
/foo/bar	io.goeasy.service.foo	Foo.Bar
/v1/foo/bar	io.goeasy.service.v1.foo	Foo.Bar
/v1/foo/bar/baz	io.goeasy.service.v1.foo	Bar.Baz
/v2/foo/bar	io.goeasy.service.v2.foo	Foo.Bar
/v2/foo/bar/baz	io.goeasy.service.v2.foo	Bar.Baz

Web Resolver

In goeasy ecosystem, the gate is not only the API Gateway. As the gate is the only entrance for external requests, besides RESTful API, it also serves static web pages and HTTP GET (for example, an OAuth 2 Redirect URI or Callback URL).

Currently following paths are reserved by the resolver for static web pages:

• The root path /
• /favicon.ico
• /portal

HTTP GET can be handled by backend service. The query string is converted to JSON by qson.

Monitoring

The gate exposes Prometheus text-based format metrics at /metrics.

Image Placeholder

The gate generates custom placeholder images on the fly at /placeholder.

You can use the images in your HTML or CSS, like this:

<img src="/placeholder?w=640&h=360">

File Uploader

The gate can save artifacts.

You can upload files with POST /o/upload. The filename is taken from the original file. Or you can use PUT /o/upload/(filename). In this case, the original file name is ignored, and the name is taken from the URL. Either case the URL to get the uploaded file is returned.

You can download files with GET /o/(filename).

Add /o/upload/* to rules to allow only authenticated uploads.

Documentation

Index

• Constants
• type Server
  • func NewServer() *Server
  • func (s *Server) Name() string
  • func (s *Server) Run()

Constants

const (
	ServiceName = "gate"
	APIPath     = "/"
	PortalPath  = "/portal/"
	UploadPath  = "/o/"
)

Types

type Server

type Server struct {
	Address        string   `json:"api_serving_address"`
	Namespace      string   `json:"namespace"`
	Production     bool     `json:"production"`
	LogOutputPaths []string `json:"logging_output_paths"`
	Domain         string   `json:"domain"`
	EnableTLS      bool     `json:"enable_api_tls"`
	EnableACME     bool     `json:"enable_api_acme"`
}

func NewServer

func NewServer() *Server

func (*Server) Name

func (s *Server) Name() string

func (*Server) Run

func (s *Server) Run()