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) SetAccessCheck(fn func(resource string, action byte, data ...any) bool)
  • 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 declares which role codes are allowed per action. Used by standalone mode (without tinywasm/rbac).

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(payload any) (any, error)
}

Creator handles entity creation. payload is the entity to create (concrete type asserted internally by the handler). Returns the created entity or an error.

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. No codec is configured by default. Use SetCodecs() to provide serialization functions before execution.

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) SetAccessCheck

func (cp *CrudP) SetAccessCheck(fn func(resource string, action byte, data ...any) bool)

SetAccessCheck configures an external access check function. When set, AllowedRoles() interface is NOT required on handlers. The function receives the handler's resource name, the action byte ('c','r','u','d'), and the raw request data (same variadic as SetUserRoles closure). Must be called before RegisterHandlers(). Mutually exclusive with SetUserRoles — use one or the other.

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, payload any) error
}

DataValidator validates payload before execution. action: 'c' create, 'r' read, 'u' update, 'd' delete.

type Deleter

type Deleter interface {
	Delete(id string) error
}

Deleter handles entity removal by ID.

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 resource name used for routing and RBAC.

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(id string) (any, error)
	List() (any, error)
}

Reader handles entity retrieval. Read returns a single entity by its string ID. List returns all entities (no filter).

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(payload any) (any, error)
}

Updater handles entity mutation. payload is the entity with updated fields. Returns the updated entity or an error.