ika

package module
v0.0.40 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Feb 13, 2025 License: MPL-2.0 Imports: 8 Imported by: 6

README

Ika

What is Ika?

Ika is a simple, modular, programmable API Gateway written in Go. It is designed to serve as a base for building a custom API gateway and have ZERO gotchas. In fact, it is so simple, that by default, it is closer to a reverse proxy than a full-fledged API Gateway. It even boasts an impressive external dependency count of 2; One which is a yaml parser used to read the configuration file, and one other to provide colored text output for slog.

Why Ika?

Ika is designed for people that value the following:

  • Zero gotchas: The original path (and path parameters) are always perfectly preserved and no extra headers will be added to the request/response. You will find no surprises when using Ika.
  • Simple: Ika is designed to be simple and easy to understand. It is not a full-fledged API Gateway, but more of a stable base to extend upon.
  • Programmable: Ika is designed to be programmable. You can easily write your own Go middleware to handle your business logic and compile it into Ika to extend its functionality.
  • Future-proof: Because Ika basically has no external dependencies, it is very future-proof. As long as Go is around and working, Ika will be too.
Features
  • Namespace support: Ika supports configuring multiple namespaces, each with its own isolated configuration which does not interfere with other namespaces.
  • Path matching: Ika can match paths and capture parameters or wildcards. It supports all the exact same patterns as http.ServeMux.
  • Path rewriting: Ika is able to rewrite the path of a request before it is sent to the backend.
  • Virtual hosting: Need to handle traffic for multiple domains? No problem, Ika supports virtual hosting.
  • Middleware support: Middleware can be applied on a namespace or per-path level. Users of Ika can write their own middleware and compile it into Ika.
What Ika is not
  • Ika is not, and never will be a full-fledged API Gateway like Kong, Tyk or KrakenD.
  • Mature. It is a new project, not yet been battle-tested in production, and has yet to see its first 1.0 release. Why don't you help us get there ;)
Performance

As of now, Ika has not been benchmarked, and in fact there is little reason to do so. Because Ika is so simple, the performance is expected to be that identical of http.Server and http.ServeMux.

Getting started

Installation

To install Ika, you can use go get:

go install github.com/alx99/ika@latest
Configuration

Ika is configured using a YAML file. The most basic configuration file might look something like this:

ika:
  gracefulShutdownTimeout: 30s
  logger:
    level: debug
    format: text

server:
  addr: :8888  # The server will listen on port 8080 for incoming traffic

namespaces:
  api:
    reqModifiers:
      - name: basic-modifier
        config:
          host: https://dummyjson.com
    middlewares:
      - name: access-log
    paths:
      /users: {}

For a full configuration reference please see ika.example.yaml and the JSON schema.

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func DefaultErrorHandler added in v0.0.37 

func DefaultErrorHandler(w http.ResponseWriter, r *http.Request, err error)

DefaultErrorHandler is the default error handler used by Ika. It writes the error to the response in JSON format if the client accepts JSON, otherwise it writes the error as plain text.

If the error implements the following interfaces:

status() int typeURI() string title() string detail() string

The response will be populated with the appropriate values.

func ToHTTPHandler added in v0.0.31 

func ToHTTPHandler(h Handler, errHandler ErrorHandler) http.Handler

ToHTTPHandler converts an Handler into an http.Handler using HandlerFunc.ToHTTPHandler.

Types

type ErrorHandler added in v0.0.32 

type ErrorHandler func(w http.ResponseWriter, r *http.Request, err error)

ErrorHandler is a function that handles errors that occur during request processing.

type Handler added in v0.0.31 

type Handler interface {
	ServeHTTP(w http.ResponseWriter, r *http.Request) error
}

Handler is identical to http.Handler except that it is able to return an error.

type HandlerFunc added in v0.0.31 

type HandlerFunc func(http.ResponseWriter, *http.Request) error

HandlerFunc is an adapter to allow the use of ordinary functions as [Handler]s.

func (HandlerFunc) ServeHTTP added in v0.0.31 

func (f HandlerFunc) ServeHTTP(w http.ResponseWriter, r *http.Request) error

func (HandlerFunc) ToHTTPHandler added in v0.0.31 

func (f HandlerFunc) ToHTTPHandler(errHandler ErrorHandler) http.Handler

ToHTTPHandler converts an Handler into an http.Handler. If the function returns an error, it will be written to the response using the provided error handler. If the error handler is nil, the error will be written as a 500 Internal Server Error.

type InjectionContext added in v0.0.31 

type InjectionContext struct {
	// Namespace indicates the namespace where the plugin is injected.
	// It is empty if not injected at the namespace or route level.
	Namespace string

	// RoutePattern specifies the route pattern where the plugin is injected.
	// It is empty if not injected at the route level.
	RoutePattern string

	// Level indicates whether the injection is at the namespace or route level.
	Level InjectionLevel

	// Logger is the logger meant for the plugin.
	Logger *slog.Logger
}

InjectionContext contains information about the context in which a plugin is injected.

type InjectionLevel added in v0.0.31 

type InjectionLevel uint8

InjectionLevel defines the granularity of plugin injection. 

const (
	// LevelRoute specifies injection on a route level.
	LevelRoute InjectionLevel = iota

	// LevelNamespace specifies injection on a namespace level.
	LevelNamespace
)

type Middleware added in v0.0.31 

type Middleware interface {
	Plugin

	// Handler wraps the given handler with custom logic for processing requests and responses.
	Handler(next Handler) Handler
}

Middleware enables plugins to modify both requests and responses.

type MiddlewareHook added in v0.0.31 

type MiddlewareHook interface {
	// HookMiddleware wraps the provided HTTP handler with custom middleware logic.
	HookMiddleware(ctx context.Context, name string, next http.Handler) (http.Handler, error)
}

TODO

type OnRequestHooker added in v0.0.32 

type OnRequestHooker interface {
	Plugin
	Middleware
}

OnRequestHooker enables hooks that run when a request is received.

It is semantically equivalent to a middleware, but is executed before all other middleware and thus is useful for things such as tracing or logging.

type Plugin added in v0.0.31 

type Plugin interface {
	// Setup initializes the plugin with the given configuration and context.
	//
	// If injected multiple times at the same level, Setup will be called multiple times.
	Setup(ctx context.Context, ictx InjectionContext, config map[string]any) error

	// Teardown cleans up potential resources used by the plugin.
	Teardown(ctx context.Context) error
}

Plugin is the common interface for all plugins in Ika.

type PluginFactory added in v0.0.31 

type PluginFactory interface {
	// Name returns the name of the plugin created by this factory.
	Name() string

	// New creates a new instance of the plugin.
	New(ctx context.Context, ictx InjectionContext) (Plugin, error)
}

PluginFactory creates new instances of a plugin.

type RequestModifier added in v0.0.31 

type RequestModifier interface {
	Plugin

	// ModifyRequest processes and returns the modified HTTP request.
	ModifyRequest(r *http.Request) error
}

RequestModifier allows plugins to modify incoming HTTP requests before processing.

type TripperHooker added in v0.0.31 

type TripperHooker interface {
	Plugin

	// HookTripper returns a new or modified [http.RoundTripper].
	// It can wrap or replace the existing transport.
	HookTripper(tripper http.RoundTripper) (http.RoundTripper, error)
}

TripperHooker allows plugins to modify the http.RoundTripper used by Ika.

Source Files

View all Source files

Directories

Path Synopsis
cmd
ika command
example module
internal
config
http/proxy
http/request
http/router
http/router/caramel
http/router/chain
Package chain provides a convenient way to chain http handlers.
 Package chain provides a convenient way to chain http handlers.
http/server
ika
iplugin
logger
pool
teardown
Package plugins contains built-in plugins for the ika API Gateway.
 Package plugins contains built-in plugins for the ika API Gateway.
accesslog module
basicauth module
fail2ban module
reqmodifier module
requestid module
pluginutil module

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.