apitool

Documentation

Overview

Package apitool provides few middlewares helping you create your app.

Tools in this package and sub-directories are opinionated, should be good to be used in small project. But it's suggested to write your own for large project.

Index

• Variables
• func CORS(h jsonapi.Handler) (ret jsonapi.Handler)
• func DefaultOTPFailHandler(r *http.Request) (err error)
• func ForceHeader(headers map[string]string) jsonapi.Middleware
• func LastModify(h jsonapi.Handler) (ret jsonapi.Handler)
• func NewCORS(opt CORSOption) jsonapi.Middleware
• func OTPCodeByForm(key string) func(*http.Request) string
• func OTPCodeByHeader(key string) func(*http.Request) string
• func ParseResponse(resp *http.Response, result interface{}) error
• func TOTPInForm(secret [10]byte, formKey string) jsonapi.Middleware
• func TOTPInHeader(secret [10]byte, headerKey string) jsonapi.Middleware
• type CORSOption
• type Client
  • func Call(method, uri string, client *http.Client) Client
• type TOTPMiddleware
  • func (m TOTPMiddleware) HOTP(c int64) (code string)
  • func (m TOTPMiddleware) Middleware(h jsonapi.Handler) (ret jsonapi.Handler)

Examples

• Client

Variables

var E403TOTP = jsonapi.E403.SetData("failed to auth with TOTP")

E403TOTP is a predefined error indicates you are failed to auth with otp

var EClient = jsonapi.Error{Code: -1}.SetData("Client error")

EClient indicates something goes wrong at client side while calling remote jsonapi

Deprecated: api client code is rewrited and placed in package callapi.

Functions

func CORS

func CORS(h jsonapi.Handler) (ret jsonapi.Handler)

CORS is a middleware simply allow any host access your api by setting "Access-Control-Allow-Origin: *"

func DefaultOTPFailHandler

func DefaultOTPFailHandler(r *http.Request) (err error)

DefaultOTPFailHandler is the default implementation for TOTP failure handler

It just returns E403TOTP

func ForceHeader

func ForceHeader(headers map[string]string) jsonapi.Middleware

ForceHeader creates a middleware to enforce response header

func LastModify

func LastModify(h jsonapi.Handler) (ret jsonapi.Handler)

LastModify handles If-Modified-Since and Last-Modified

It detects if there's "If-Modified-Since" header in request and "Last-Modified" in response. If both exist and modified time <= request, the response is discarded and 304 is replied.

It's no-op if handler returns any error.

// If browser send If-Modified-Since >= dateA, 304 is returned, "hello" otherwise.
//
// If browser send If-Modified-Since < dateA, "hello" is always replied.
func h1(r jsonapi.Request) (interface{}, error) {
    r.W().Header().Set("Last-Mdified", dateA.UTC().Format(http.TimeFormat))
    return "hello", nil
}

// Always return 404 to browser.
func h2(r jsonapi.Request) (interface{}, error) {
    r.W().Header().Set("Last-Mdified", dateA.UTC().Format(http.TimeFormat))
    return 1, jsonapi.E404
}

func NewCORS

func NewCORS(opt CORSOption) jsonapi.Middleware

NewCORS creates a middleware to set CORS headers

Fields with zero value will not be set.

func OTPCodeByForm

func OTPCodeByForm(key string) func(*http.Request) string

OTPCodeByForm grabs TOTP value from post form

func OTPCodeByHeader

func OTPCodeByHeader(key string) func(*http.Request) string

OTPCodeByHeader grabs TOTP value from custom header

func ParseResponse

func ParseResponse(resp *http.Response, result interface{}) error

ParseResponse parses response of a jsonapi

It's caller's response to close response body.

If any io error or json decoding error occurred, an EClient.SetOrigin(the_error) returns.

Deprecated: api client code is rewrited and placed in package callapi.

func TOTPInForm

func TOTPInForm(secret [10]byte, formKey string) jsonapi.Middleware

TOTPInForm is a helper function to create TOTPMiddleware

• OTP code is passed in post form specified in formKey
• secret is 10 bytes binary string, DO NOT USE PLAIN TEXT for best security.

It is identical to the following code, which is also actual implementation:

return (TOTPMiddleware{
    Secret: secret,
    GetCode: OTPCodeByForm(formKey),
    Failed: DefaultOTPFailHandler,
}).Middleware

func TOTPInHeader

func TOTPInHeader(secret [10]byte, headerKey string) jsonapi.Middleware

TOTPInHeader is a helper function to create TOTPMiddleware

• OTP code is passed in custom HTTP header specified by headerKey.
• secret is 10 bytes binary string, DO NOT USE PLAIN TEXT for best security.

It is identical to the following code, which is also actual implementation:

return (TOTPMiddleware{
    Secret: secret,
    GetCode: OTPCodeByHeader(headerKey),
    Failed: DefaultOTPFailHandler,
}).Middleware

Types

type CORSOption

type CORSOption struct {
	Origin        string
	ExposeHeaders []string
	Headers       []string
	MaxAge        uint64
	Credential    bool
	Methods       []string
}

CORSOption defines supported parameters used by NewCORS()

type Client

type Client interface {
	// Synchronized call
	//
	// If any io error or json decoding error occurred, an
	// EClient.SetOrigin(the_error) returns.
	Exec(param, result interface{}) error
	// Asynchronized call, Client take response to close the channel
	// result is guaranteed to be filled when error returns.
	//
	// If any io error or json decoding error occurred, an
	// EClient.SetOrigin(the_error) returns.
	Do(param, result interface{}) chan error
}

Client is a helper to simplify the process of calling jsonapi

Any error during the call process will immediately return as jsonapi.InternalError.SetOrigin(the_error)

Deprecated: api client code is rewrited and placed in package callapi.

Example

// This Source Code Form is subject to the terms of the Mozilla Public
// License, v. 2.0. If a copy of the MPL was not distributed with this
// file, You can obtain one at https://mozilla.org/MPL/2.0/.

package main

import (
	"fmt"
	"net/http"
	"net/http/httptest"

	"github.com/raohwork/jsonapi"
)

// ParamGreeting represents parameters of Greeting API
type ParamGreeting struct {
	Name    string
	Surname string
}

// RespGreeting represents returned type of Greeting API
type RespGreeting struct {
	Name    string
	Surname string
	Greeted bool
}

// greeting is handler of Greeting API
func Greeting(r jsonapi.Request) (interface{}, error) {
	var p ParamGreeting
	if err := r.Decode(&p); err != nil {
		return nil, jsonapi.APPERR.SetData(
			"parameter format error",
		).SetCode("EParamFormat")
	}

	return RespGreeting{
		Name:    p.Name,
		Surname: p.Surname,
		Greeted: true,
	}, nil
}

// RunAPIServer creates and runs an API server
func RunAPIServer() *httptest.Server {
	http.Handle("/greeting", jsonapi.Handler(Greeting))
	return httptest.NewServer(http.DefaultServeMux)
}

func main() {
	// start the API server
	server := RunAPIServer()
	defer server.Close()

	client := Call("POST", server.URL+"/greeting", nil)

	var resp RespGreeting
	err := client.Exec(ParamGreeting{Name: "John", Surname: "Doe"}, &resp)
	if err != nil {
		fmt.Println(err)
		return
	}

	fmt.Printf(
		"Have we greeted to %s %s? %v",
		resp.Name, resp.Surname, resp.Greeted,
	)

}

Output:

Have we greeted to John Doe? true

func Call

func Call(method, uri string, client *http.Client) Client

Call creates an Client to a jsonapi entry

It will use http.DefaultClient if c == nil, but it's not recommended.

Deprecated: api client code is rewrited and placed in package callapi.

type TOTPMiddleware

type TOTPMiddleware struct {
	// 80bits binary secret, REQUEIRED
	Secret [10]byte
	// how many digits should a code be, at least 6
	//
	// any value less than 6 will be forced to 6
	Digit int
	// how to get code from request, leave nil to use default implementation,
	// which loads code from X-OTP-CODE header
	//
	// for best security, it is not suggested to load code from URL query
	GetCode func(r *http.Request) string
	// which kinds of error is returned if failed to auth, leave nil to use
	// default implementation, which returns 403 error
	Failed func(r *http.Request) error
}

TOTPMiddleware represents a middleware to auth client with TOTP before execution

The TOTP implementation is this middleware has following restrictions:

• Accepts only two windows: current and previous one.

func (TOTPMiddleware) HOTP

func (m TOTPMiddleware) HOTP(c int64) (code string)

HOTP implements RFC4226

The signature of this function is designed for use within TOTPMiddleware.

func (TOTPMiddleware) Middleware

func (m TOTPMiddleware) Middleware(h jsonapi.Handler) (ret jsonapi.Handler)

Middleware is the *real* middleware part of TOTPMiddleware