BeamFoundry Open Source on BeamFoundry Rays

Rays Core

Mon, 01 Jan 0001 00:00:00 +0000

Rays Core

Rays is a powerful, enterprise-grade Dependency Injection (DI) and Inversion of Control (IoC) framework for Go, built by BeamFoundry.

Inspired by mature ecosystems like Spring Boot, Rays brings structured lifecycles, annotation-driven configuration, and robust dependency wiring to Go, while respecting Go’s idiomatic use of composition and interfaces. It eliminates boilerplate wiring, enforces clean boundaries, and makes your Go applications highly testable.

Key Features

Annotation-Driven, but Type-Safe: We use struct tags (@:"Inject") for declaring dependencies, but rely on Go’s strict typing to ensure the container wires the correct pointers.
Encapsulation Matters: Unlike manual DI which forces you to expose dependencies via public fields or constructor arguments, Rays natively injects into private fields. Your internal state remains protected.
Two-Phase Bootstrapping: To safely handle circular dependencies—a common pain point in large systems—Rays separates instantiation/injection from initialization.
Context-Aware Scoping: Singletons are great for services, but short-lived state requires a different approach. Rays introduces Foundry[T] to bridge the gap between global services and request-scoped prototypes.

Example

package main

import (
 "github.com/BeamFoundry/rays/pkg/core"
 "github.com/BeamFoundry/rays/pkg/lang"
 "github.com/BeamFoundry/rays"
)

// 1. Define a Repository
type Database struct {
 core.Component // Stereotype
 dsn string
}

func (db *Database) New() *Database {
 db.dsn = "postgres://localhost/mydb"
 return db
}

// 2. Define a Service
type UserService struct {
 core.Service //
 db *Database `@:"Inject"` // Private field injection!
 logger core.Logging `@:"Inject"`
}

func (s *UserService) PostConstruct() lang.Error {
 s.logger.Info("UserService ready!","connection", s.db.dsn)
 return nil
}

// 3. Define an Application, hosting a Run method.
type BatchUserApplication struct {
 core.Application
 userService *UserService `@:"Inject"`
 logger core.Logging `@:"Inject"`
}

// 4. Define a Run method
func (b *BatchUserApplication) Run(wg *sync.WaitGroup) {
 wg.Add(1) // 1. Register this worker with the global WaitGroup

 b.logger.Info("BatchUserApplication Run started...")

 go func() {
 defer wg.Done() // 2. Ensure we decrement the WaitGroup when finished

 b.logger.Info("BatchUserApplication is running...")

 // Background loop logic goes here...
 for {
 time.Sleep(10 * time.Second)
 }
 }()
}

// 5. Boot the Container
func main() {
 ctx := rays.ApplicationContext()

 if err := ctx.Initialize(); err != nil {
 err.LogErrorWithStackTrace()
 return
 }

 ctx.Run() // Runs application lifecycle
}

Rays ORM

Mon, 01 Jan 0001 00:00:00 +0000

Rays ORM

Rays ORM is the official database integration package for the BeamFoundry Rays framework, bringing the magic of Spring Data-style repositories to Go using GORM.

By bridging Rays’ Inversion of Control (IoC) container with GORM and ThreadLocal storage, this package completely eliminates database connection boilerplate, automatic repository method generation, and context-passing for transactions.

Key Features

Auto-Generated Repository Methods: By simply defining a function signature like findByName func(string) *User on your repository struct, Rays ORM will automatically generate the underlying GORM query logic and bind it to that field during the container’s wiring phase.
ThreadLocal Transactions: Using github.com/timandy/routine, Rays ORM implements true ThreadLocal storage for Go. When a Service starts a transaction, the *gorm.DB transaction object is bound to the current goroutine. Downstream repositories transparently inherit this transaction without requiring you to pass it via function arguments.
IoC Managed DB: You define a standard *gorm.DB Beam, and the framework’s GormTxManager handles the rest.
Secure by Default (SQL Injection Prevention): The auto-generated query builder does not concatenate raw strings. It automatically translates your method names into parameterized queries using ? placeholders, ensuring that all database interactions are natively protected against SQL injection attacks without requiring manual sanitization.

Example

package repositories

import (
 "time"
 . "github.com/BeamFoundry/rays-orm"
 . "github.com/BeamFoundry/rays/pkg/core"
 . "github.com/BeamFoundry/rays/pkg/lang"
)

type User struct {
 ID uint
 Name string
 Age uint
 CreatedAt time.Time
 UpdatedAt time.Time
}

// 1. Define the public contract
type UserRepositoryInterface interface {
 OrmRepositoryInterface[User, uint]

 FindByName(name string) *User
 FindActiveUsers(status string, minAge int) ([]*User, Error)
 FindByAgeRangeDynamic(min, max int, customFilters ...OrmQueryFunc) []*User
}

// 2. Define the implementation
type UserRepository struct {
 OrmRepository[User, uint]

 findByName func(string) *User
 findByStatusAndAgeGreaterThan func(string, int) ([]*User, Error)
 findByAgeBetweenOrderByNameAscAndIdDesc func(int, int, ...OrmQueryFunc) []*User
}

// 3. Expose the generated functions
func (this *UserRepository) FindByName(name string) *User {
 return this.findByName(name)
}

func (this *UserRepository) FindActiveUsers(status string, minAge int) ([]*User, Error) {
 return this.findByStatusAndAgeGreaterThan(status, minAge)
}

func (this *UserRepository) FindByAgeRangeDynamic(min, max int, customFilters ...OrmQueryFunc) []*User {
 return this.findByAgeBetweenOrderByNameAscAndIdDesc(min, max, customFilters...)
}

Rays Web Security

Mon, 01 Jan 0001 00:00:00 +0000

Rays Web Security

Rays Web Security brings the declarative power and robust architecture of Spring Security directly to Go.

Built natively on top of the Rays IoC container, this package provides authentication, authorization, and protection against common exploits. It integrates seamlessly with web frameworks (like Rays Fiber) to secure your HTTP endpoints using clean, fluent builder chains.

It deeply integrates with Rays Fiber via HttpSecurity configurations, allowing you to automatically protect your endpoints using expressive, chainable security rules.

Rays Fiber

Mon, 01 Jan 0001 00:00:00 +0000

Rays Fiber

Rays Fiber seamlessly integrates the popular, Express-inspired Go Fiber web framework with the Rays IoC Container.

By bringing Fiber into the IoC ecosystem, you can build blazing-fast web APIs using clean, object-oriented controllers, effortless dependency injection, and declarative configuration.

Key Features

Injected Controllers: Define your HTTP handlers as methods on a struct, allowing you to seamlessly inject repositories, services, and configurations using the Rays @:"Inject" tag.
Centralized Lifecycle: The HTTP server lifecycle (startup and graceful shutdown) is automatically managed by the Rays application context.
Declarative Routing: Define endpoint HTTP methods and paths directly via struct tags, keeping your routing logic exactly where the handler code lives.

Example

package controllers

import (
 "github.com/gofiber/fiber/v3"
 . "github.com/BeamFoundry/rays-fiber/pkg/core"
 . "github.com/BeamFoundry/rays/pkg/core"
 . "github.com/BeamFoundry/rays/pkg/web"
)

type UserController struct {
 FiberController
 RequestMapping `Path:"/api/users"`
 
 // Dependencies are auto-wired
 userService *UserService `@:"Inject"`
}

func (c *UserController) GetUser(
 // Declarative endpoint mapping
 _ struct{ RequestMapping `Method:"GET" Path:"/:id"` },
 ctx *fiber.Ctx,
) error {
 id := ctx.Params("id")
 user := c.userService.FindByID(id)
 return ctx.JSON(user)
}

BeamFoundry Open Source on BeamFoundry Rays

Rays Core

Rays Core

Links

Key Features

Example

Rays ORM

Rays ORM

Links

Key Features

Example

Rays Web Security

Rays Web Security

Rays Fiber

Rays Fiber

Links

Key Features

Example