arpc

README

arpc

ARPC is the Acoshift's opinionated HTTP-RPC styled api

Installation

go get -u github.com/acoshift/arpc/v2

HTTP Status Code

ARPC will response http with only these 3 status codes

• 200 OK - function works as expected
• 400 Bad Request - developer (api caller) error, should never happened in production
• 500 Internal Server Error - server error, should never happened (server broken)

Example Responses

Success Result

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
	"ok": true,
	"result": {
		// result object
	}
}

Error Result

• Validate error
• Precondition failed
• User error

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
	"ok": false,
	"error": {
		"message": "some error message"
	}
}

Function not found

• Developer (api caller) call not exists function

HTTP/1.1 400 Bad Request
Content-Type: application/json; charset=utf-8

{
	"ok": false,
	"error": {
		"message": "not found"
	}
}

Unsupported Content-Type

• Developer (api caller) send invalid content type

HTTP/1.1 400 Bad Request
Content-Type: application/json; charset=utf-8

{
	"ok": false,
	"error": {
		"message": "unsupported content type"
	}
}

Internal Server Error

• Server broken !!!

HTTP/1.1 500 Internal Server Error
Content-Type: application/json; charset=utf-8

{
	"ok": false,
	"error": {} // internal error always return empty object
}

How to use

package main

import (
	"context"
	"log"
	"net/http"
	
	"github.com/acoshift/arpc/v2"
)

func main() { 
	// create new manager 
	am := arpc.New()

	mux := http.NewServeMux()
	mux.Handle("/hello", am.Handle(Hello))
	
	// start server 
	log.Fatal(http.ListenAndServe(":8080", mux))
}

type HelloParams struct {
	Name string `json:"name"`
}

func (r *HelloParams) Valid() error {
	if r.Name == "" {
		return arpc.NewError("name required")
	}
	return nil
}

type HelloResult struct {
	Message string `json:"message"`
}

func Hello(ctx context.Context, req *HelloParams) (*HelloResult, error) {
	return &HelloResult{
		Message: "hello " + req.Name,
	}, nil
}

License

MIT

Documentation

Index

• Variables
• func NewError(message string) error
• func NewErrorCode(code, message string) error
• func NewProtocolError(code, message string) error
• func WrapError(err error) error
• type Decoder
• type Empty
  • func (Empty) UnmarshalForm(v url.Values) error
  • func (Empty) UnmarshalMultipartForm(v *multipart.Form) error
  • func (Empty) UnmarshalRequest(r *http.Request) error
• type Encoder
• type Error
  • func (err *Error) Code() string
  • func (err *Error) Error() string
  • func (err *Error) MarshalJSON() ([]byte, error)
  • func (err *Error) Message() string
  • func (err *Error) OKError()
  • func (err *Error) Unwrap() error
• type ErrorEncoder
• type FormUnmarshaler
• type Manager
  • func New() *Manager
  • func (m *Manager) Decode(r *http.Request, v any) error
  • func (m *Manager) Encode(w http.ResponseWriter, r *http.Request, v any)
  • func (m *Manager) EncodeError(w http.ResponseWriter, r *http.Request, err error)
  • func (m *Manager) Handler(f any) http.Handler
  • func (m *Manager) Middleware(f Middleware) func(http.Handler) http.Handler
  • func (m *Manager) NotFound(w http.ResponseWriter, r *http.Request)
  • func (m *Manager) NotFoundHandler() http.Handler
  • func (m *Manager) OnError(f func(w http.ResponseWriter, r *http.Request, req any, err error))
  • func (m *Manager) OnOK(f func(w http.ResponseWriter, r *http.Request, req any, res any))
• type Middleware
• type MiddlewareContext
  • func (ctx *MiddlewareContext) Deadline() (deadline time.Time, ok bool)
  • func (ctx *MiddlewareContext) Done() <-chan struct{}
  • func (ctx *MiddlewareContext) Err() error
  • func (ctx *MiddlewareContext) Request() *http.Request
  • func (ctx *MiddlewareContext) ResponseWriter() http.ResponseWriter
  • func (ctx *MiddlewareContext) SetRequest(r *http.Request)
  • func (ctx *MiddlewareContext) SetRequestContext(nctx context.Context)
  • func (ctx *MiddlewareContext) SetResponseWriter(w http.ResponseWriter)
  • func (ctx *MiddlewareContext) Value(key interface{}) interface{}
• type MultipartFormUnmarshaler
• type OKError
• type ProtocolError
  • func (err *ProtocolError) Error() string
• type RequestAdapter
• type RequestUnmarshaler
• type Validatable

Variables

var (
	ErrNotFound    = NewProtocolError("", "not found")
	ErrUnsupported = NewProtocolError("", "unsupported content type")
)

predefined errors

Functions

func NewError

func NewError(message string) error

NewError creates new Error with message

func NewErrorCode

func NewErrorCode(code, message string) error

NewErrorCode creates new Error with code and message

func NewProtocolError

func NewProtocolError(code, message string) error

func WrapError

func WrapError(err error) error

WrapError wraps given error with OKError

Types

type Decoder

type Decoder func(*http.Request, any) error

Decoder is the request decoder

type Empty

type Empty struct{}

func (Empty) UnmarshalForm

func (Empty) UnmarshalForm(v url.Values) error

func (Empty) UnmarshalMultipartForm

func (Empty) UnmarshalMultipartForm(v *multipart.Form) error

func (Empty) UnmarshalRequest

func (Empty) UnmarshalRequest(r *http.Request) error

type Encoder

type Encoder func(http.ResponseWriter, *http.Request, any)

Encoder is the response encoder

type Error

type Error struct {
	// contains filtered or unexported fields
}

Error always return 200 status with false ok value use this error for validate, precondition failed, etc.

func (*Error) Code

func (err *Error) Code() string

Code returns error code

func (*Error) Error

func (err *Error) Error() string

Error implements error

func (*Error) MarshalJSON

func (err *Error) MarshalJSON() ([]byte, error)

MarshalJSON implements json.Marshaler

func (*Error) Message

func (err *Error) Message() string

Message returns error message

func (*Error) OKError

func (err *Error) OKError()

OKError implements OKError

func (*Error) Unwrap

func (err *Error) Unwrap() error

Unwrap implements errors.Unwarp

type ErrorEncoder

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

ErrorEncoder is the error response encoder

type FormUnmarshaler

type FormUnmarshaler interface {
	UnmarshalForm(v url.Values) error
}

FormUnmarshaler interface

type Manager

type Manager struct {
	Decoder      Decoder
	Encoder      Encoder
	ErrorEncoder ErrorEncoder
	Validate     bool // set to true to validate request after decode using Validatable interface

	WrapError func(error) error
	// contains filtered or unexported fields
}

func New

func New() *Manager

New creates new arpc manager

func (*Manager) Decode

func (m *Manager) Decode(r *http.Request, v any) error

func (*Manager) Encode

func (m *Manager) Encode(w http.ResponseWriter, r *http.Request, v any)

func (*Manager) EncodeError

func (m *Manager) EncodeError(w http.ResponseWriter, r *http.Request, err error)

func (*Manager) Handler

func (m *Manager) Handler(f any) http.Handler

func (*Manager) Middleware

func (m *Manager) Middleware(f Middleware) func(http.Handler) http.Handler

func (*Manager) NotFound

func (m *Manager) NotFound(w http.ResponseWriter, r *http.Request)

func (*Manager) NotFoundHandler

func (m *Manager) NotFoundHandler() http.Handler

func (*Manager) OnError

func (m *Manager) OnError(f func(w http.ResponseWriter, r *http.Request, req any, err error))

OnError calls f when error

func (*Manager) OnOK

func (m *Manager) OnOK(f func(w http.ResponseWriter, r *http.Request, req any, res any))

OnOK calls f before encode ok response

type Middleware

type Middleware func(r *MiddlewareContext) error

type MiddlewareContext

type MiddlewareContext struct {
	// contains filtered or unexported fields
}

func (*MiddlewareContext) Deadline

func (ctx *MiddlewareContext) Deadline() (deadline time.Time, ok bool)

func (*MiddlewareContext) Done

func (ctx *MiddlewareContext) Done() <-chan struct{}

func (*MiddlewareContext) Err

func (ctx *MiddlewareContext) Err() error

func (*MiddlewareContext) Request

func (ctx *MiddlewareContext) Request() *http.Request

func (*MiddlewareContext) ResponseWriter

func (ctx *MiddlewareContext) ResponseWriter() http.ResponseWriter

func (*MiddlewareContext) SetRequest

func (ctx *MiddlewareContext) SetRequest(r *http.Request)

func (*MiddlewareContext) SetRequestContext

func (ctx *MiddlewareContext) SetRequestContext(nctx context.Context)

func (*MiddlewareContext) SetResponseWriter

func (ctx *MiddlewareContext) SetResponseWriter(w http.ResponseWriter)

func (*MiddlewareContext) Value

func (ctx *MiddlewareContext) Value(key interface{}) interface{}

type MultipartFormUnmarshaler

type MultipartFormUnmarshaler interface {
	UnmarshalMultipartForm(v *multipart.Form) error
}

MultipartFormUnmarshaler interface

type OKError

type OKError interface {
	OKError()
}

OKError implements this interface to mark errors as 200

type ProtocolError

type ProtocolError struct {
	Code    string `json:"code,omitempty"`
	Message string `json:"message,omitempty"`
}

ProtocolError always returns 400 status with false ok value only use this error for invalid protocol usages

func (*ProtocolError) Error

func (err *ProtocolError) Error() string

type RequestAdapter

type RequestAdapter interface {
	AdaptRequest(r *http.Request)
}

RequestAdapter converts request to arpc before decode

type RequestUnmarshaler

type RequestUnmarshaler interface {
	UnmarshalRequest(r *http.Request) error
}

RequestUnmarshaler interface

type Validatable

type Validatable interface {
	Valid() error
}

Validatable interface