jsonkit

README

jsonkit

A comprehensive JSON and Protocol Buffer utility package for Go HTTP applications. Provides streamlined JSON handling with strict validation, Protocol Buffer support, and convenient HTTP request/response helpers.

Features

• HTTP Integration: Direct JSON binding for HTTP requests and responses
• Protocol Buffer Support: Seamless JSON serialization for protobuf messages
• Strict Validation: Prevents unknown fields and malformed JSON
• Error Handling: Comprehensive error reporting for debugging
• Type Safe: Full Go type safety with generics support

Installation

go get github.com/entrylens/godash/jsonkit

Quick Start

package main

import (
    "net/http"
    "github.com/entrylens/godash/jsonkit"
)

type User struct {
    Name string `json:"name"`
    Age  int    `json:"age"`
}

func handleUser(w http.ResponseWriter, r *http.Request) {
    var user User

    // Bind JSON request body to struct
    if err := jsonkit.BindRequestBody(r, &user); err != nil {
        http.Error(w, err.Error(), http.StatusBadRequest)
        return
    }

    // Send JSON response
    if err := jsonkit.JSONResponse(w, http.StatusOK, user); err != nil {
        http.Error(w, err.Error(), http.StatusInternalServerError)
    }
}

API Reference

Core JSON Functions

Marshal

func Marshal(v interface{}) ([]byte, error)

Marshals a Go struct to JSON bytes.

Example:

user := User{Name: "Alice", Age: 30}
data, err := jsonkit.Marshal(user)
// data = []byte(`{"name":"Alice","age":30}`)

UnMarshal

func UnMarshal(data []byte, v interface{}) error

Unmarshals JSON bytes to a Go struct with strict validation.

Example:

data := []byte(`{"name":"Bob","age":25}`)
var user User
err := jsonkit.UnMarshal(data, &user)
// user = User{Name: "Bob", Age: 25}

HTTP Request/Response Functions

BindRequestBody

func BindRequestBody(r *http.Request, v interface{}) error

Binds JSON from HTTP request body to a Go struct.

Features:

• Disallows unknown fields
• Validates JSON structure
• Handles request body reading

Example:

func handleCreateUser(w http.ResponseWriter, r *http.Request) {
    var user User
    if err := jsonkit.BindRequestBody(r, &user); err != nil {
        // Handle validation errors
        return
    }
    // Process user...
}

JSONResponse

func JSONResponse(w http.ResponseWriter, statusCode int, v interface{}) error

Writes a Go struct as JSON to HTTP response.

Features:

• Sets proper Content-Type header
• Handles HTTP status codes
• Error handling for marshaling failures

Example:

func handleGetUser(w http.ResponseWriter, r *http.Request) {
    user := User{Name: "Alice", Age: 30}
    if err := jsonkit.JSONResponse(w, http.StatusOK, user); err != nil {
        http.Error(w, err.Error(), http.StatusInternalServerError)
    }
}

Protocol Buffer Functions

MarshalProto

func MarshalProto(v proto.Message) ([]byte, error)

Marshals a Protocol Buffer message to JSON.

Features:

• Emits unpopulated fields
• Optimized for protobuf serialization
• Compatible with protobuf JSON spec

Example:

message := &pb.User{Name: "Alice", Age: 30}
data, err := jsonkit.MarshalProto(message)

UnMarshalProto

func UnMarshalProto(data []byte, v proto.Message) error

Unmarshals JSON to a Protocol Buffer message.

Example:

data := []byte(`{"name":"Bob","age":25}`)
message := &pb.User{}
err := jsonkit.UnMarshalProto(data, message)

BindProtoRequestBody

func BindProtoRequestBody(r *http.Request, v proto.Message) error

Binds JSON from HTTP request body to a Protocol Buffer message.

Example:

func handleCreateProtoUser(w http.ResponseWriter, r *http.Request) {
    message := &pb.User{}
    if err := jsonkit.BindProtoRequestBody(r, message); err != nil {
        http.Error(w, err.Error(), http.StatusBadRequest)
        return
    }
    // Process protobuf message...
}

ProtoJSONResponse

func ProtoJSONResponse(w http.ResponseWriter, statusCode int, v proto.Message) error

Writes a Protocol Buffer message as JSON to HTTP response.

Example:

func handleGetProtoUser(w http.ResponseWriter, r *http.Request) {
    message := &pb.User{Name: "Alice", Age: 30}
    if err := jsonkit.ProtoJSONResponse(w, http.StatusOK, message); err != nil {
        http.Error(w, err.Error(), http.StatusInternalServerError)
    }
}

Error Handling

The package provides comprehensive error handling:

// Validation errors
if err := jsonkit.BindRequestBody(r, &user); err != nil {
    switch {
    case strings.Contains(err.Error(), "unexpected extra JSON data"):
        // Handle extra JSON data
    case strings.Contains(err.Error(), "unknown field"):
        // Handle unknown fields
    default:
        // Handle other JSON errors
    }
}

Validation Features

• Unknown Field Detection: Prevents extra fields in JSON
• Type Validation: Ensures correct data types
• Required Field Checking: Validates struct tags
• Malformed JSON Detection: Catches syntax errors

Performance Considerations

• Efficient Memory Usage: Minimal allocations
• Streaming Support: Direct HTTP body reading
• Optimized Marshaling: Fast JSON serialization
• Zero-Copy Where Possible: Efficient data handling

Testing

go test ./jsonkit/...

Dependencies

• encoding/json - Core JSON functionality
• google.golang.org/protobuf - Protocol Buffer support
• net/http - HTTP integration

License

MIT License - see LICENSE for details.

Documentation

Index

• func BindProtoRequestBody(r *http.Request, v proto.Message) error
• func BindRequestBody(r *http.Request, v interface{}) error
• func JSONResponse(w http.ResponseWriter, statusCode int, v interface{}) error
• func Marshal(v interface{}) ([]byte, error)
• func MarshalProto(v proto.Message) ([]byte, error)
• func ProtoJSONResponse(w http.ResponseWriter, statusCode int, v proto.Message) error
• func UnMarshal(data []byte, v interface{}) error
• func UnMarshalProto(data []byte, v proto.Message) error

Functions

func BindProtoRequestBody

func BindProtoRequestBody(r *http.Request, v proto.Message) error

BindProtoRequestBody decodes JSON from the request body into a Protobuf message.

func BindRequestBody

func BindRequestBody(r *http.Request, v interface{}) error

func JSONResponse

func JSONResponse(w http.ResponseWriter, statusCode int, v interface{}) error

JSONResponse writes a Go struct as JSON to the response.

func Marshal

func Marshal(v interface{}) ([]byte, error)

func MarshalProto

func MarshalProto(v proto.Message) ([]byte, error)

func ProtoJSONResponse

func ProtoJSONResponse(w http.ResponseWriter, statusCode int, v proto.Message) error

ProtoJSONResponse writes a Protobuf message as JSON to the response.

func UnMarshal

func UnMarshal(data []byte, v interface{}) error

func UnMarshalProto

func UnMarshalProto(data []byte, v proto.Message) error