crudp

README

CRUDP

A JSON/binary CRUD protocol for isomorphic Go applications. Limits its responsibility to handler registration and execution, delegating transport to separate packages.

Features

• Isomorphic: Same handler code on frontend (WASM) and backend (Server).
• Automatic Endpoints: Generates HTTP routes (GET /users/{id}, POST /users) automatically.
• Protocol Agnostic: Decoupled from HTTP, SSE or any transport layer.
• Batch Processing: Logic to execute multiple operations from a single request.
• TinyGo Compatible: Optimized for small WASM binaries.

Documentation

• example/README.md: Step-by-step integration guide for Server and WASM
• docs/ACCESS_CONTROL.md: Role-based access control (RBAC) configuration
• docs/INITIAL_VISION.md: Vision and design principles
• docs/HANDLER_REGISTER.md: Handler interfaces and registration
• docs/PACKET_STRUCTURE.md: Protocol packet structures

---

Contributing

Documentation

Index

• func ActionToMethod(action byte) string
• func MethodToAction(method string) byte
• type AccessDeniedHandler
• type AccessLevel
• type BatchRequest
• type BatchResponse
• type Creator
• type CrudP
  • func New() *CrudP
  • func (cp *CrudP) ApplyMiddleware(handler http.Handler) http.Handler
  • func (cp *CrudP) CallHandler(handlerID uint8, action byte, data ...any) (any, error)
  • func (cp *CrudP) Execute(req *BatchRequest, inject ...any) (*BatchResponse, error)
  • func (cp *CrudP) GetHandlerName(handlerID uint8) string
  • func (cp *CrudP) IsDevMode() bool
  • func (cp *CrudP) RegisterHandlers(handlers ...any) error
  • func (cp *CrudP) RegisterRoutes(mux *http.ServeMux)
  • func (cp *CrudP) SetAccessDeniedHandler(fn AccessDeniedHandler)
  • func (cp *CrudP) SetCodecs(encode, decode func(input any, output any) error)
  • func (cp *CrudP) SetDevMode(enabled bool)
  • func (cp *CrudP) SetLog(log func(...any))
  • func (cp *CrudP) SetUserRoles(fn func(data ...any) []byte)
• type DataValidator
• type Deleter
• type MiddlewareProvider
• type NamedHandler
• type Packet
• type PacketResult
• type Reader
• type Request
• type Response
• type Updater

Functions

func ActionToMethod

func ActionToMethod(action byte) string

ActionToMethod converts CRUD action byte to HTTP method

func MethodToAction

func MethodToAction(method string) byte

MethodToAction converts HTTP method to CRUD action byte

Types

type AccessDeniedHandler

type AccessDeniedHandler func(handler string, action byte, userRoles []byte, allowedRoles []byte, errMsg string)

AccessDeniedHandler defines the callback for failed access attempts

type AccessLevel

type AccessLevel interface {
	AllowedRoles(action byte) []byte
}

AccessLevel defines role-based access control (required if CRUD implemented)

type BatchRequest

type BatchRequest struct {
	Packets []Packet `json:"packets"`
}

BatchRequest is what is sent in the POST /sync

type BatchResponse

type BatchResponse struct {
	Results []PacketResult `json:"results"`
}

BatchResponse is what is received by SSE or as HTTP response

type Creator

type Creator interface {
	Create(data ...any) any
}

Separate CRUD interfaces - handlers implement only what they need Return `any` which internally can be slice for multiple items

type CrudP

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

CrudP handles automatic handler processing

func New

func New() *CrudP

New creates a new CrudP instance with binary codec by default

func (*CrudP) ApplyMiddleware

func (cp *CrudP) ApplyMiddleware(handler http.Handler) http.Handler

ApplyMiddleware collects all middleware from handlers and wraps the provided handler

func (*CrudP) CallHandler

func (cp *CrudP) CallHandler(handlerID uint8, action byte, data ...any) (any, error)

CallHandler searches and calls the handler directly by shared index

func (*CrudP) Execute

func (cp *CrudP) Execute(req *BatchRequest, inject ...any) (*BatchResponse, error)

Execute processes a BatchRequest and returns a BatchResponse inject contains values to prepend to handler data (e.g., context, http.Request)

func (*CrudP) GetHandlerName

func (cp *CrudP) GetHandlerName(handlerID uint8) string

GetHandlerName returns the handler name by its ID

func (*CrudP) IsDevMode

func (cp *CrudP) IsDevMode() bool

IsDevMode returns the current development mode status

func (*CrudP) RegisterHandlers

func (cp *CrudP) RegisterHandlers(handlers ...any) error

RegisterHandlers prepares the shared handler table

func (*CrudP) RegisterRoutes

func (cp *CrudP) RegisterRoutes(mux *http.ServeMux)

func (*CrudP) SetAccessDeniedHandler

func (cp *CrudP) SetAccessDeniedHandler(fn AccessDeniedHandler)

SetAccessDeniedHandler configures a callback for failed access attempts

func (*CrudP) SetCodecs

func (cp *CrudP) SetCodecs(encode, decode func(input any, output any) error)

SetCodecs configures custom serialization functions

func (*CrudP) SetDevMode

func (cp *CrudP) SetDevMode(enabled bool)

SetDevMode enables or disables development mode (bypasses access checks)

func (*CrudP) SetLog

func (cp *CrudP) SetLog(log func(...any))

SetLog configures a custom logging function

func (*CrudP) SetUserRoles

func (cp *CrudP) SetUserRoles(fn func(data ...any) []byte)

SetUserRoles configures the current user's roles extractor. Access checks are enabled when RegisterRoutes is called on the server.

type DataValidator

type DataValidator interface {
	ValidateData(action byte, data ...any) error
}

DataValidator validates complete data before action (required if CRUD implemented)

type Deleter

type Deleter interface {
	Delete(data ...any) any
}

type MiddlewareProvider

type MiddlewareProvider interface {
	Middleware(next http.Handler) http.Handler
}

MiddlewareProvider allows handlers to provide global HTTP middleware

type NamedHandler

type NamedHandler interface {
	HandlerName() string
}

NamedHandler provides the unique name for the entity (required if CRUD implemented)

type Packet

type Packet struct {
	Action    byte     `json:"action"`
	HandlerID uint8    `json:"handler_id"`
	ReqID     string   `json:"req_id"`
	Data      [][]byte `json:"data"`
}

Packet represents both requests and responses of the protocol

type PacketResult

type PacketResult struct {
	Packet             // Embed Packet complete for symmetry with BatchRequest
	MessageType uint8  `json:"message_type"` // 0=Normal, 1=Info, 2=Error, 3=Warning, 4=Success
	Message     string `json:"message"`      // Message for the user
}

type Reader

type Reader interface {
	Read(data ...any) any
}

type Request

type Request struct {
	ReqID string   `json:"req_id"`
	Data  [][]byte `json:"data"`
}

Request represents a single operation request for automatic endpoints

type Response

type Response struct {
	ReqID       string   `json:"req_id"`
	Data        [][]byte `json:"data"`
	MessageType uint8    `json:"message_type"`
	Message     string   `json:"message"`
}

Response represents a single operation response for automatic endpoints

type Updater

type Updater interface {
	Update(data ...any) any
}