micro/api/api.go

183 lines
3.7 KiB
Go
Raw Normal View History

package api // import "go.unistack.org/micro/v3/api"
2019-06-03 20:44:43 +03:00
import (
"errors"
"regexp"
"strings"
"go.unistack.org/micro/v3/metadata"
"go.unistack.org/micro/v3/register"
"go.unistack.org/micro/v3/server"
2019-06-03 20:44:43 +03:00
)
// nolint: revive
// Api interface
type Api interface {
2020-04-01 14:07:50 +03:00
// Initialise options
Init(...Option) error
// Get the options
Options() Options
// Register a http handler
Register(*Endpoint) error
// Register a route
Deregister(*Endpoint) error
// Implementation of api
String() string
}
// Options holds the options
type Options struct{}
2020-04-01 14:07:50 +03:00
// Option func signature
2020-04-01 14:07:50 +03:00
type Option func(*Options) error
2019-06-03 20:44:43 +03:00
// Endpoint is a mapping between an RPC method and HTTP endpoint
type Endpoint struct {
// Name Greeter.Hello
2019-06-03 20:44:43 +03:00
Name string
// Desciption for endpoint
2019-06-03 20:44:43 +03:00
Description string
// Handler e.g rpc, proxy
2019-06-03 20:44:43 +03:00
Handler string
// Body destination
// "*" or "" - top level message value
// "string" - inner message value
Body string
// Host e.g example.com
2019-06-03 20:44:43 +03:00
Host []string
// Method e.g GET, POST
2019-06-03 20:44:43 +03:00
Method []string
// Path e.g /greeter. Expect POSIX regex
2019-06-03 20:44:43 +03:00
Path []string
// Stream flag
Stream bool
2019-06-03 20:44:43 +03:00
}
// Service represents an API service
type Service struct {
// Name of service
Name string
// Endpoint for this service
2019-06-03 20:44:43 +03:00
Endpoint *Endpoint
// Services that provides service
Services []*register.Service
2019-06-03 20:44:43 +03:00
}
// Encode encodes an endpoint to endpoint metadata
func Encode(e *Endpoint) map[string]string {
if e == nil {
return nil
}
// endpoint map
ep := make(map[string]string)
// set vals only if they exist
set := func(k, v string) {
if len(v) == 0 {
return
}
ep[k] = v
2019-06-03 20:44:43 +03:00
}
set("endpoint", e.Name)
set("description", e.Description)
set("handler", e.Handler)
set("method", strings.Join(e.Method, ","))
set("path", strings.Join(e.Path, ","))
set("host", strings.Join(e.Host, ","))
set("body", e.Body)
return ep
2019-06-03 20:44:43 +03:00
}
// Decode decodes endpoint metadata into an endpoint
func Decode(e metadata.Metadata) *Endpoint {
2019-06-03 20:44:43 +03:00
if e == nil {
return nil
}
ep := &Endpoint{}
ep.Name, _ = e.Get("endpoint")
ep.Description, _ = e.Get("description")
epmethod, _ := e.Get("method")
ep.Method = []string{epmethod}
eppath, _ := e.Get("path")
ep.Path = []string{eppath}
ephost, _ := e.Get("host")
ep.Host = []string{ephost}
ep.Handler, _ = e.Get("handler")
ep.Body, _ = e.Get("body")
return ep
2019-06-03 20:44:43 +03:00
}
// Validate validates an endpoint to guarantee it won't blow up when being served
func Validate(e *Endpoint) error {
if e == nil {
return errors.New("endpoint is nil")
}
if len(e.Name) == 0 {
return errors.New("name required")
}
for _, p := range e.Path {
ps := p[0]
pe := p[len(p)-1]
switch {
case ps == '^' && pe == '$':
if _, err := regexp.CompilePOSIX(p); err != nil {
return err
}
case ps == '^' && pe != '$':
return errors.New("invalid path")
case ps != '^' && pe == '$':
return errors.New("invalid path")
2019-06-03 20:44:43 +03:00
}
}
if len(e.Handler) == 0 {
return errors.New("invalid handler")
}
return nil
}
/*
Design ideas
// Gateway is an api gateway interface
type Gateway interface {
// Register a http handler
Handle(pattern string, http.Handler)
// Register a route
RegisterRoute(r Route)
// Init initialises the command line.
// It also parses further options.
Init(...Option) error
// Run the gateway
Run() error
}
// NewGateway returns a new api gateway
func NewGateway() Gateway {
return newGateway()
}
*/
// WithEndpoint returns a server.HandlerOption with endpoint metadata set
//
// Usage:
//
// proto.RegisterHandler(service.Server(), new(Handler), api.WithEndpoint(
// &api.Endpoint{
// Name: "Greeter.Hello",
// Path: []string{"/greeter"},
// },
// ))
func WithEndpoint(e *Endpoint) server.HandlerOption {
return server.EndpointMetadata(e.Name, Encode(e))
}