blest

README

BLEST Go

The Go reference implementation of BLEST (Batch-able, Lightweight, Encrypted State Transfer), an improved communication protocol for web APIs which leverages JSON, supports request batching by default, and provides a modern alternative to REST. It includes an example for Gin.

To learn more about BLEST, please visit the website: https://blest.jhunt.dev

For a front-end implementation in React, please visit https://github.com/jhuntdev/blest-react

Features

• Built on JSON - Reduce parsing time and overhead
• Request Batching - Save bandwidth and reduce load times
• Compact Payloads - Save even more bandwidth
• Single Endpoint - Reduce complexity and facilitate introspection
• Fully Encrypted - Improve data privacy

Installation

Install BLEST Go from Go Packages.

go get github.com/jhuntdev/blest-go

Usage

The Default struct of this library has an interface similar to Gin. It also provides a Router struct with a Handle method for use in an existing NodeJS application and an HttpClient struct with a Request method for making BLEST HTTP requests.

package main

import "github.com/jhuntdev/blest-go"

// Create some middleware (optional)
func authMiddleware(body interface{}, context *map[string]interface{}) {
	headers, ok := context.(map[string]interface{})["headers"].(map[string]interface{})
	if !ok || headers["auth"] != "myToken" {
		return nil, errors.New("Unauthorized")
	}
	(*context)["user"] = map[string]interface{}{
		// user info for example
	}
}

// Create a route controller
func greetController(body interface{}, context *map[string]interface{}) (interface{}, error) {
	name, ok := body["name"].(string)
	if !ok {
		return nil, errors.New("name not found or has an invalid type")
	}
	greeting := fmt.Sprintf("Hi, %v!", name)
	return map[string]interface{}{
		"greeting": greeting,
	}, nil
}

func main() {
	r := blest.Default()
	r.Use(authMiddleware)
	r.Route("greet", greetController)
	r.Run() // listen and serve on 0.0.0.0:8080
}

Router

package main

import {
	"github.com/jhuntdev/blest-go"
	"github.com/gin-gonic/gin"
}

// Create some middleware (optional)
func authMiddleware(body interface{}, context *map[string]interface{}) {
	headers, ok := context.(map[string]interface{})["headers"].(map[string]interface{})
	if !ok || headers["auth"] !== "myToken" {
		return nil, errors.New("Unauthorized")
	}
	(*context)["user"] = map[string]interface{}{
		"name": name,
	}
}

// Create a route controller
func greetController(body interface{}, context *map[string]interface{}) (interface{}, error) {
	user, ok := (*context)["user"].(map[string]interface{})
	if !ok {
		return nil, errors.New("user not found or has an invalid type")
	}
	name, ok := user["name"].(string)
	if !ok {
		return nil, errors.New("name not found or has an invalid type")
	}
	greeting := fmt.Sprintf("Hi, %v!", name)
	return map[string]interface{}{
		"greeting": greeting,
	}, nil
}

// Create your router
router := blest.Router()
router.Use(authMiddleware)
router.Route("greet", greetController)

func main() {
	r := gin.Default()
	r.POST("/", func(c *gin.Context) {
		var req gin.Request
		if err := c.ShouldBindJSON(&req); err != nil {
			c.JSON(400, gin.H{
				"error": "Invalid JSON payload",
			})
			return
		}
		// Use the router
		response, e := router.Handle(req.Data, nil)
		if e !== nil {
			c.JSON(500, e)
		} else {
			c.JSON(200, response)
		}
	})
	r.Run() // listen and serve on 0.0.0.0:8080
}

HttpClient

package main

import (
	"encoding/json"
	"errors"
	"fmt"
	"log"

	"github.com/jhuntdev/blest-go"
)

func main() {
	// Set headers (optional)
	httpHeaders := map[string]string{
		"Authorization": "Bearer token",
	}

	// Create a client
	client := blest.NewHttpClient("http://localhost:8080", map[string]interface{}{"httpHeaders": httpHeaders})
	
	// Send a request
	result, err := client.Request("greet", map[string]interface{}{ "name": "Steve" }, map[string]interface{}{"auth": "myToken"})
	if err != nil {
		// Do something in case of error
	} else {
		// Do something with the result
	}
}

License

This project is licensed under the MIT License.

Documentation

Index

• func NewBlestError(message string, args ...interface{}) error
• func NewHttpServer(requestHandler RequestHandler, args ...interface{}) *http.Server
• type BlestError
  • func (be *BlestError) Error() string
• type HttpClient
  • func NewHttpClient(url string, args ...interface{}) *HttpClient
  • func (c *HttpClient) Process()
  • func (c *HttpClient) Request(route string, args ...interface{}) (map[string]interface{}, error)
• type RequestHandler
• type Route
• type Router
  • func Default(options map[string]interface{}) *Router
  • func NewRouter(args ...interface{}) *Router
  • func (r *Router) Describe(route string, config map[string]interface{}) error
  • func (r *Router) Handle(requests [][]interface{}, context map[string]interface{}) ([][4]interface{}, map[string]interface{})
  • func (r *Router) Merge(router *Router) error
  • func (r *Router) Namespace(prefix string, router *Router) error
  • func (r *Router) Route(route string, args ...interface{})
  • func (r *Router) Run()
  • func (r *Router) Use(handlers ...interface{})

Functions

func NewBlestError

func NewBlestError(message string, args ...interface{}) error

func NewHttpServer

func NewHttpServer(requestHandler RequestHandler, args ...interface{}) *http.Server

Types

type BlestError

type BlestError struct {
	Message    string
	StatusCode int
	Code       string
}

func (*BlestError) Error

func (be *BlestError) Error() string

type HttpClient

type HttpClient struct {
	Url          string
	Options      map[string]interface{}
	HttpHeaders  map[string]string
	MaxBatchSize int
	Queue        [][]interface{}
	Timeout      *time.Timer
	Emitter      *eventEmitter
}

func NewHttpClient

func NewHttpClient(url string, args ...interface{}) *HttpClient

func (*HttpClient) Process

func (c *HttpClient) Process()

func (*HttpClient) Request

func (c *HttpClient) Request(route string, args ...interface{}) (map[string]interface{}, error)

type RequestHandler

type RequestHandler func(requests [][]interface{}, context map[string]interface{}) ([][4]interface{}, map[string]interface{})

type Route

type Route struct {
	Handler     []interface{}
	Description string
	Schema      interface{}
	Visible     bool
	Validate    bool
	Timeout     int
}

type Router

type Router struct {
	Options       map[string]interface{}
	Introspection bool
	Middleware    []interface{}
	Afterware     []interface{}
	Timeout       int
	Routes        map[string]Route
}

func Default

func Default(options map[string]interface{}) *Router

func NewRouter

func NewRouter(args ...interface{}) *Router

func (*Router) Describe

func (r *Router) Describe(route string, config map[string]interface{}) error

func (*Router) Handle

func (r *Router) Handle(requests [][]interface{}, context map[string]interface{}) ([][4]interface{}, map[string]interface{})

func (*Router) Merge

func (r *Router) Merge(router *Router) error

func (*Router) Namespace

func (r *Router) Namespace(prefix string, router *Router) error

func (*Router) Route

func (r *Router) Route(route string, args ...interface{})

func (*Router) Run

func (r *Router) Run()

func (*Router) Use

func (r *Router) Use(handlers ...interface{})