# README

Box - A Robust Message Processing Library for Go

Box is a high-performance, transactional message processing library that provides reliable message queuing and processing capabilities using PostgreSQL as the backing store.

Features

📦 PostgreSQL-backed message storage
🔄 FIFO (First-In-First-Out) message processing
🔒 Transactional guarantees
🎯 Message type-based routing
📊 Consumer offset tracking
🚀 Batch processing support
🔌 Pluggable message handlers
📈 Processing status monitoring

Installation

go get github.com/thefabric-io/box

Quick Start

1. Initialize the Box

import (
    "github.com/thefabric-io/box"
    "github.com/thefabric-io/box/pgbox"
)

// Create a new PostgreSQL box
box := pgbox.NewPostgresBox("myschema", "mytopic", "mytype")

2. Create a Message Handler

type MyHandler struct {}

func (h *MyHandler) HandleEvent(ctx context.Context, tx transactional.Transaction, msg box.Message) error {
    // Process your message here
    return nil
}

3. Set Up a Subscriber

// Create a FIFO subscriber
subscriber := box.NewFIFOSubscriber(
    transactional,    // Your transactional interface implementation
    "myconsumer",     // Consumer name
    box,              // The box instance
    100,             // Batch size
    time.Second * 5,  // Wait time between empty batches
)

// Register message handler
subscriber.RegisterHandler("message_type", &MyHandler{})

4. Start Processing

// Create a manager
manager, _ := box.NewManager()

// Add subscriber
manager.AddProcessors(subscriber)

// Start processing
ctx := context.Background()
manager.Run(ctx)

Architecture

Box implements a message processing system with the following key components:

Box : Interface for message storage and retrieval
Message : Core message structure with metadata
Handler : Message processing logic
Subscriber : Message consumption and routing
Manager : Orchestrates multiple subscribers

Configuration

The PostgreSQL box can be configured with:

Schema name
Topic name
Message type
Batch size
Wait time between empty batches

Best Practices

Transaction Management
- Always use the provided transaction context
- Handle transaction rollbacks appropriately
Error Handling
- Implement proper error handling in handlers
- Use context for timeouts and cancellation
Message Types
- Use consistent message type naming
- Register handlers for all expected message types
Monitoring
- Track processing status using the Status() method
- Implement proper logging in handlers