apid

README

apid-core

apid-core is a library that provides a container for publishing APIs that provides core services to its plugins including configuration, API publishing, data access, and a local pub/sub event system.

Disambiguation: You might be looking for the executable builder, apid.

Services

apid provides the following services:

• apid.API()
• apid.Config()
• apid.Data()
• apid.Events()
• apid.Log()

Initialization of services and plugins

A driver process must initialize apid and its plugins like this:

apid.Initialize(factory.DefaultServicesFactory()) // when done, all services are available
apid.InitializePlugins() // when done, all plugins are running
api := apid.API() // access the API service
err := api.Listen() // start the listener

Once apid.Initialize() has been called, all services are accessible via the apid package functions as details above.

Plugins

The only requirement of an apid plugin is to register itself upon init(). However, generally plugins will access the Log service and some kind of driver (via API or Events), so it's common practice to see something like this:

var log apid.LogService
 
func init() {
  apid.RegisterPlugin(initPlugin)
}

func initPlugin(services apid.Services) error {

  log = services.Log().ForModule("myPluginName") // note: could also access via `apid.Log().ForModule()`
  
  services.API().HandleFunc("/verifyAPIKey", handleRequest)
}

func handleRequest(w http.ResponseWriter, r *http.Request) {
  // respond to request
}

Utils

apid-core/util package offers common util functions for apid plugins:

• Generate/Validate UUIDs
• Long Polling
• Debounce Events

Running Tests

go test $(glide novendor)

apid.Data() service

This service provides the primitives to perform SQL operations on the database. It also provides the provision to alter DB connection pool settings via ConfigDBMaxConns, ConfigDBIdleConns and configDBConnsTimeout configuration parameters. They currently are defaulted to 1000 connections, 1000 connections and 120 seconds respectively. More details on this can be found at https://golang.org/pkg/database/sql

Making http.Client calls through Forward proxy server

If forward proxy server related parameters are set, util.Transport() will provide the Transport roundtripper with the forward proxy parameters set.

Documentation

Index

• Variables
• func Initialize(s Services)
• func InitializePlugins(versionNumber string)
• func RegisterPlugin(plugin PluginInitFunc, pluginData PluginData)
• func ShutdownPluginsAndWait() error
• type APIService
  • func API() APIService
• type ConfigService
  • func Config() ConfigService
• type DB
• type DataService
  • func Data() DataService
• type Event
• type EventDeliveryEvent
• type EventHandler
• type EventHandlerFunc
• type EventSelector
• type EventsService
  • func Events() EventsService
• type LogService
  • func Log() LogService
• type PluginData
• type PluginInitFunc
• type PluginsInitializedEvent
• type Route
• type Router
• type Services
  • func AllServices() Services
• type ShutdownEvent
• type Tx

Variables

var (
	APIDInitializedEvent = systemEvent{"apid initialized"}
	APIListeningEvent    = systemEvent{"api listening"}
	PluginVersionTracker []PluginData
)

Functions

func Initialize

func Initialize(s Services)

func InitializePlugins

func InitializePlugins(versionNumber string)

func RegisterPlugin

func RegisterPlugin(plugin PluginInitFunc, pluginData PluginData)

func ShutdownPluginsAndWait

func ShutdownPluginsAndWait() error

Shutdown all the plugins that have registered for ShutdownEventSelector. This call will block until either all required plugins shutdown, or a timeout occurred.

Types

type APIService

type APIService interface {
	Listen() error
	Handle(path string, handler http.Handler) Route
	HandleFunc(path string, handlerFunc http.HandlerFunc) Route
	Vars(r *http.Request) map[string]string

	// for testing
	Router() Router
}

func API

func API() APIService

type ConfigService

type ConfigService interface {
	SetDefault(key string, value interface{})
	Set(key string, value interface{})
	Get(key string) interface{}

	GetBool(key string) bool
	GetFloat64(key string) float64
	GetInt(key string) int
	GetString(key string) string
	GetDuration(key string) time.Duration
	IsSet(key string) bool
}

func Config

func Config() ConfigService

type DB

type DB interface {
	Ping() error
	Prepare(query string) (*sql.Stmt, error)
	Exec(query string, args ...interface{}) (sql.Result, error)
	Query(query string, args ...interface{}) (*sql.Rows, error)
	QueryRow(query string, args ...interface{}) *sql.Row
	Begin() (Tx, error)
	Stats() sql.DBStats
	SetConnMaxLifetime(d time.Duration)
	SetMaxIdleConns(n int)
	SetMaxOpenConns(n int)
	QueryStructs(dest interface{}, query string, args ...interface{}) error
}

type DataService

type DataService interface {
	DB() (DB, error)
	DBForID(id string) (db DB, err error)

	DBVersion(version string) (db DB, err error)
	DBVersionForID(id, version string) (db DB, err error)

	// will set DB to close and delete when no more references
	ReleaseDB(version string)
	ReleaseCommonDB()
	ReleaseDBForID(id, version string)
}

func Data

func Data() DataService

type Event

type Event interface{}

type EventDeliveryEvent

type EventDeliveryEvent struct {
	Description string
	Selector    EventSelector
	Event       Event
	Count       int
}

type EventHandler

type EventHandler interface {
	Handle(event Event)
}

type EventHandlerFunc

type EventHandlerFunc func(event Event)

type EventSelector

type EventSelector string

const (
	SystemEventsSelector  EventSelector = "system event"
	ShutdownEventSelector EventSelector = "shutdown event"
	ShutdownTimeout       time.Duration = 10 * time.Second
)

const EventDeliveredSelector EventSelector = "event delivered"

type EventsService

type EventsService interface {
	// Publish an event to the selector.
	// It will send a copy of the delivered event to the returned channel, after all listeners have responded to the event.
	// Call "Emit()" for non-blocking, "<-Emit()" for blocking.
	Emit(selector EventSelector, event Event) chan Event

	// publish an event to the selector, call the passed handler when all listeners have responded to the event
	EmitWithCallback(selector EventSelector, event Event, handler EventHandlerFunc)

	// when an event matching selector occurs, run the provided handler
	Listen(selector EventSelector, handler EventHandler)

	// when an event matching selector occurs, run the provided handler function
	ListenFunc(selector EventSelector, handler EventHandlerFunc)

	// when an event matching selector occurs, run the provided handler function and stop listening
	ListenOnceFunc(selector EventSelector, handler EventHandlerFunc)

	// remove a listener
	StopListening(selector EventSelector, handler EventHandler)

	// shut it down
	Close()
}

func Events

func Events() EventsService

type LogService

type LogService interface {
	Debugf(format string, args ...interface{})
	Infof(format string, args ...interface{})
	Printf(format string, args ...interface{})
	Warnf(format string, args ...interface{})
	Warningf(format string, args ...interface{})
	Errorf(format string, args ...interface{})
	Fatalf(format string, args ...interface{})
	Panicf(format string, args ...interface{})

	Debug(args ...interface{})
	Info(args ...interface{})
	Print(args ...interface{})
	Warn(args ...interface{})
	Warning(args ...interface{})
	Error(args ...interface{})
	Fatal(args ...interface{})
	Panic(args ...interface{})

	Debugln(args ...interface{})
	Infoln(args ...interface{})
	Println(args ...interface{})
	Warnln(args ...interface{})
	Warningln(args ...interface{})
	Errorln(args ...interface{})
	Fatalln(args ...interface{})
	Panicln(args ...interface{})

	WithField(key string, value interface{}) LogService

	ForModule(name string) LogService
	ForEnvironment(name string) LogService
}

func Log

func Log() LogService

type PluginData

type PluginData struct {
	Name      string
	Version   string
	ExtraData map[string]interface{}
}

type PluginInitFunc

type PluginInitFunc func(Services) (PluginData, error)

type PluginsInitializedEvent

type PluginsInitializedEvent struct {
	Description string
	// using slice member will make the type "PluginsInitializedEvent" uncomparable
	Plugins     []PluginData
	ApidVersion string
}

use reflect.DeepEqual to compare this type

type Route

type Route interface {
	Methods(methods ...string) Route
}

type Router

type Router interface {
	Handle(path string, handler http.Handler) Route
	HandleFunc(path string, handlerFunc http.HandlerFunc) Route
	ServeHTTP(w http.ResponseWriter, req *http.Request)
}

for testing

type Services

type Services interface {
	API() APIService
	Config() ConfigService
	Data() DataService
	Events() EventsService
	Log() LogService
}

func AllServices

func AllServices() Services

type ShutdownEvent

type ShutdownEvent struct {
	Description string
}

type Tx

type Tx interface {
	Commit() error
	Exec(query string, args ...interface{}) (sql.Result, error)
	ExecContext(ctx context.Context, query string, args ...interface{}) (sql.Result, error)
	Prepare(query string) (*sql.Stmt, error)
	PrepareContext(ctx context.Context, query string) (*sql.Stmt, error)
	Query(query string, args ...interface{}) (*sql.Rows, error)
	QueryContext(ctx context.Context, query string, args ...interface{}) (*sql.Rows, error)
	QueryRow(query string, args ...interface{}) *sql.Row
	QueryRowContext(ctx context.Context, query string, args ...interface{}) *sql.Row
	Rollback() error
	Stmt(stmt *sql.Stmt) *sql.Stmt
	StmtContext(ctx context.Context, stmt *sql.Stmt) *sql.Stmt
	QueryStructs(dest interface{}, query string, args ...interface{}) error
}