beaver-kit

beaver-kit

A GoLang package providing a modular abstraction layer for web frameworks, simplifying dependency management and ensuring a consistent API for developers.

beaver-kit is a versatile GoLang package that serves as a modular abstraction layer for web frameworks, empowering developers to effortlessly manage dependencies while maintaining a consistent API. With beaver-kit, developers can integrate various web framework packages seamlessly, enabling flexibility and future-proofing for their applications.

Key Features

• Dependency Management: beaver-kit simplifies dependency management by abstracting away specific implementations, allowing developers to integrate different web framework packages without altering the core codebase. Whether updating to newer versions or transitioning to alternative packages, beaver-kit ensures a smooth experience for developers.

• Consistent API: As maintainers update underlying dependencies, beaver-kit guarantees a consistent API for users. Developers can rely on beaver-kit's stable interface to access essential functions and features, shielding their applications from the complexities of dependency updates.

• Simplified Maintenance: By centralizing dependency management within beaver-kit, maintenance tasks become streamlined for developers. With the ability to update packages seamlessly, beaver-kit minimizes the burden of maintenance and reduces the likelihood of compatibility issues.

Installation

go get github.com/gobeaver/beaver-kit

Usage

Integrating beaver-kit into your project is straightforward. Simply import the package and leverage its intuitive API to manage dependencies effortlessly. Whether you're developing a new application or maintaining an existing one, beaver-kit offers a reliable solution for managing web framework dependencies with ease.

import (
    "github.com/gobeaver/beaver-kit/config"
    "github.com/gobeaver/beaver-kit/krypto"
    "github.com/gobeaver/beaver-kit/captcha"
    "github.com/gobeaver/beaver-kit/filevalidator"
)

// Use the packages with zero configuration (defaults)
jwt := krypto.NewJWT(krypto.JWTOptions{})
validator := filevalidator.NewDefault()

// Or with environment configuration
loader := config.NewLoader()
loader.Load()

jwt := krypto.NewJWTFromConfig()
captchaService := captcha.NewServiceFromConfig()

Sub-Modules

beaver-kit is organized into specialized sub-modules, each focusing on specific aspects of web development:

Krypto Module

The Krypto subpackage is responsible for string generation, encryption and decryption, hashing, and secure token generation. It provides essential cryptographic functionalities to ensure data security within your application.

Key features:

• Password hashing (Argon2id and Bcrypt)
• JWT token generation and validation
• AES-GCM encryption/decryption
• RSA key management
• SHA-256 hashing
• Secure token generation

For documentation on the krypto subpackage, please refer to Krypto doc.

Captcha Module

A unified interface for implementing various CAPTCHA services in your web applications.

Supported services:

• Google reCAPTCHA (v2 and v3)
• hCaptcha
• Cloudflare Turnstile

Key features:

• Clean, unified interface for multiple CAPTCHA providers
• Context support for proper timeout handling
• HTML generation for frontend integration
• Comprehensive error handling

Config Module

A flexible, optional configuration system that supports automatic package registration and multiple configuration patterns.

Key features:

• Optional by default (all packages work without configuration files)
• Auto-registration of packages when imported
• Support for environment variables and global config
• Type-safe configuration structs
• Zero dependencies

FileKit Module

Seamless file handling and upload management with support for multiple cloud storage providers.

Features:

• Local file system support
• Cloud storage adapters (AWS S3, Google Cloud Storage)
• Streaming support for large files
• Flexible options for file operations

FileValidator Module

A comprehensive file validation package that protects against various security threats.

Key features:

• File size, MIME type, and extension validation
• Content-based validation (deep file inspection)
• Protection against:
  • Zip bombs
  • Malicious images
  • Dangerous PDFs
• Stream validation for large files
• Detailed error types for better user feedback

Quick Start Examples

Basic Captcha Implementation

// Create a CAPTCHA service
recaptcha := captcha.NewGoogleCaptcha(
    "your-site-key",
    "your-secret-key",
    2, // version 2
)

// In your template
htmlElement := recaptcha.GenerateHTML()

// Validate submission
valid, err := recaptcha.Validate(ctx, token, clientIP)

File Validation

// Create validator with image constraints
validator := filevalidator.New(filevalidator.ImageOnlyConstraints())

// Validate uploaded file
if err := validator.Validate(fileHeader); err != nil {
    // Handle validation error
}

JWT Token Generation

// Create user claims
claims := krypto.UserClaims{
    First: "John",
    Last: "Doe",
    Token: "user-identifier",
}

// Generate token
token, err := krypto.NewHs256AccessToken(claims)

Configuration

beaver-kit supports multiple configuration patterns:

1. Zero Configuration: All packages work with sensible defaults
2. Direct Configuration: Pass options directly to constructors
3. Environment Variables: Configure via environment
4. Global Configuration: Load configuration from files

Example environment variables:

# Krypto configuration
KRYPTO_JWT_KEY=your-secret-key
KRYPTO_JWT_ALGO=HS256

# Captcha configuration
CAPTCHA_ENABLED=true
CAPTCHA_SERVICE=recaptcha
CAPTCHA_SECRET_KEY=your-secret-key

# File validation
FILEVALIDATOR_MAX_SIZE=10MB
FILEVALIDATOR_ALLOWED_TYPES=image/jpeg,image/png

Development Guide

Commands

# Run all tests
go test ./...

# Test specific package
go test ./krypto -v

# Format code
go fmt ./...

# Lint code
golint ./...

# Check for issues
go vet ./...

Code Style Guidelines

• Naming: CamelCase for exported items, camelCase for unexported
• Errors: Use fmt.Errorf with %w for wrapping errors
• Testing: Table-driven tests with descriptive test case names
• Documentation: Add comments for all exported functions and types
• Imports: Organize by standard lib first, then third-party
• Interfaces: Design with clean interfaces for testability
• Error Handling: Always check errors and provide context

Contributing

We welcome contributions! When adding new features:

1. Follow the existing code style
2. Add comprehensive tests
3. Update documentation
4. Keep the API consistent
5. Ensure backward compatibility

License

This project is licensed under the License included in the repository.

Support

For issues, feature requests, or questions:

• Check the documentation
• Open an issue on GitHub
• Refer to individual module READMEs for specific guidance

Acknowledgments

beaver-kit is built with ❤️ by the Beaver team, focused on providing high-performance, production-ready tools for the Go community.