BeamFoundry Rays on BeamFoundry Rays Core

1. Introduction

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

Introduction & Philosophy

Go is famous for its simplicity and explicit dependency passing. However, as Go applications scale to hundreds of services, repositories, and cross-cutting concerns, manual wiring (often done in massive init() functions or main.go) becomes fragile and difficult to maintain.

BeamFoundry Rays solves this by introducing a robust Inversion of Control (IoC) container.

Core Principles

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.

Error Handling

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

Error Handling

If a container fails to boot, you need to know exactly where the wiring failed. Rays replaces standard Go error handling during the lifecycle with a richer Error interface that captures stack traces and key-value attributes automatically.

import . "github.com/BeamFoundry/rays/pkg/lang"

func (s *UserService) PostConstruct() Error {
 if s.db == nil {
 err := NewError("WiringError", "Database pointer is nil")

 // AddAttribute does not return the Error object, so it cannot be chained.
 err.AddAttribute("component", "UserService")
 err.AddAttribute("action", "PostConstruct")

 return err
 }
 return nil
}

Integration with Logging

Because Rays integrates its lang package directly with the logging framework (covered in Chapter 4), an Error can report itself seamlessly.

Message Catalogs & Pluralization

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

Message Catalogs & Pluralization

Rays simplifies message localization by letting you define translation catalogs directly in your YAML configuration files. Messages are automatically loaded into LocaleMessageBundle instances, with full support for positional parameters, Unicode CLDR pluralization rules, and numeric ranges.

Defining Messages in YAML

Message catalogs are organized by locale under the localization.messages property in your application.yaml file. Rays recognizes four distinct categories of localized messages:

Category	Description	Placeholders
`translation`	Simple string translations. Positional parameters are denoted by `{0}`, `{1}`, `{2}`, etc.	`{0}`, `{1}`, `{2}`, …
`cardinal`	Plural rules determined by item quantities (e.g., “1 day” vs. “5 days”).	`{0}` (the formatted number)
`ordinal`	Plural rules determined by position or rank (e.g., “1st”, “2nd”, “3rd”).	`{0}` (the formatted number)
`ranges`	Plural rules for intervals between two numbers (e.g., “1-3 days”).	`{0}`, `{1}` (the start and end numbers)

Complete YAML Example

localization:
 messages:
 en:
 translation:
 welcome: "Welcome"
 welcome_user: "Welcome, {0} {1}!"
 fields.registration.username: "Username"
 fields.registration.password: "Password"
 fields.registration.confirm: "Confirm Password"
 cardinal:
 days.left:
 ONE: "{0} day remaining"
 OTHER: "{0} days remaining"
 ordinal:
 competition.place:
 ONE: "{0}st place"
 TWO: "{0}nd place"
 FEW: "{0}rd place"
 OTHER: "{0}th place"
 ranges:
 days.range:
 OTHER: "{0}-{1} days"

 fr:
 translation:
 welcome: "Bienvenue"
 welcome_user: "Bienvenue, {0} {1} !"
 fields.registration.username: "Nom d'utilisateur"
 fields.registration.password: "Mot de passe"
 fields.registration.confirm: "Confirmation du mot de passe"
 cardinal:
 days.left:
 ONE: "{0} jour restant"
 OTHER: "{0} jours restants"
 ordinal:
 competition.place:
 ONE: "{0}er prix"
 OTHER: "{0}e prix"
 ranges:
 days.range:
 ONE: "{0}-{1} jour"
 OTHER: "{0}-{1} jours"

CLDR Plural Rules

Different languages follow different rules for pluralization. In English, cardinal numbers only distinguish between ONE (1) and OTHER (0, 2, 3, …). Other languages like Polish, Russian, or Arabic use additional categories such as FEW or MANY.

Stereotypes & Beams

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

Stereotypes & Beams

In Rays, a “Beam” is any object managed by the IoC container. You declare a struct as a Beam by embedding a Stereotype.

🧹 Simplifying with Dot Imports

Before we dive in, a quick note on style. To keep your domain code clean and free of repetitive package prefixes, it is highly recommended to use Go’s dot import feature for the core and lang packages.

This allows you to use framework types like Service, Component, and Error directly as if they were native keywords. We will use this convention in the following examples.

2. Quickstart

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

Quickstart

📦 Installation

go get github.com/BeamFoundry/rays

🚀 The Minimal Application

Here is a complete example of a Rays application. It’s not really functional but demonstrate the following :

Beam are defined by marker Stereotype interfaces like Component, Service and Application.
Dependency injection is done via struct tag.
A PostConstruct method can be defined on any Beam. They will be called once an instance is injected.
A custom Error type.
A Run method can be defined on any Beam. It does not need to be on an Application.

Notice how UserService does not need a constructor taking *Database as an argument.

Container Configuration

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

Container Configuration

Rays integrates internationalization cleanly into its Inversion of Control (IoC) container. By declaring an i18n Configuration Beam, you can bind YAML configuration properties, configure default and auxiliary locales, load validator translation packs, and publish i18n services for injection throughout your application.

1. Defining Configuration Properties

First, define a struct embedding ConfigurationProperties to bind the localization section from your application.yaml file:

package config

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

// LocalizationProperties binds messages from application.yaml under "localization".
type LocalizationProperties struct {
 ConfigurationProperties `Name:"localization"`
 messages map[string]LocalizedMessages
}

Rays automatically maps the YAML properties to the internal LocalizedMessages struct containing translation, cardinal, ordinal, and ranges maps.

Dependency Injection

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

Dependency Injection

Rays relies on struct tags to identify injection points.

Basic Injection

Add @:"Inject" to any field that is a pointer to a struct or an interface. The container will automatically find and wire the matching Beam by type.

Note: You cannot inject into a concrete value type (like db Database instead of db *Database), as this would break the singleton pattern by copying the struct by value.

import . "github.com/BeamFoundry/rays/pkg/core"

type OrderService struct {
 Service
 inventory *InventoryService `@:"Inject"`
 payment PaymentGateway `@:"Inject"` // Interfaces do not need a '*'
}

Private Field Superiority

Idiomatic Go encourages hiding internal state. Rays uses reflection to inject into private fields, meaning your dependencies aren’t exposed to other packages.

Enum Types

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

Type-Safe Enums

Go does not have native, strict enums. This often leads to configuration bugs where an invalid string from a YAML file is happily parsed into a string field, only to fail deep within the application logic.

Rays solves this with Enum[T]. It strictly binds string values from YAML into custom Go types and validates them during the framework’s Instantiation phase.

1. Define the Enum Type

You can define your enums using a struct to hold the variants as fields.

Lifecycle Management

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

Lifecycle Management

Rays uses a strict, deterministic phase model to ensure application stability.

Phase 1: Instantiation & Wiring

The container scans for all embedded stereotypes.
It calls New() on structs that implement it to set up initial state.
It maps ConfigurationProperties from YAML.
It resolves all @:"Inject" tags and assigns pointers (or interface references).

Note: Because no business logic runs in Phase 1, Rays natively handles Circular Dependencies between singletons.

Web & Template Integration

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

Web & Template Integration

Internationalized web applications must dynamically determine the user’s preferred language for each incoming HTTP request without requiring developers to manually pass a locale or context parameter through every service, repository, and template call.

Rays solves this using ThreadLocaleContextHolder for request-scoped locale management and LocaleFuncMap for seamless integration with Go’s standard html/template package.

1. Request-Scoped Locale Management

How It Works

ThreadLocaleContextHolder is powered by thread-local storage (routine.ThreadLocal). When an HTTP request enters your application:

4. Logging Framework

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

Logging Framework

Enterprise applications require structured, leveled, and contextual logging.

Rays provides a dedicated configurable, logging framework.

The `Logging` Interface

Rays logging is powered by Go’s standard slog library under the hood, providing high-performance, structured logging. However, standard slog natively lacks a “Trace” level for highly granular debugging.

Rays extends the standard implementation by adding full support for the Trace level, including the corresponding Trace() and TraceContext() functions on the Logging interface.

Configuration & Profiles

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

Configuration & Profiles

In enterprise applications, configuration and environment management go hand-in-hand.

Rays provides a unified system to bind YAML configurations directly to your structs, override them based on active profiles (e.g., dev, prod), and conditionally load specific components depending on the environment.

1. Binding Data

Embed ConfigurationProperties and define the YAML path via the Name tag.

NOTE: Rays strictly enforces a 1-to-1 parity between your YAML files and your Go code. The yaml tag is not honored. Only properties with the exact same case name as the Go struct field will be injected.

Localized Struct Validation

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

Localized Struct Validation

Web frameworks and API routers typically bind request payloads to structs and validate them using Go-Playground Validator. However, default validation outputs suffer from two major problems:

Error descriptions are in English only.
Field names reflect raw Go struct fields (e.g., "ConfirmPassword" or "user_email") rather than user-friendly UI labels.

Rays’ MessageSourceValidator solves both problems by translating validation rules into the active request locale and replacing field names with localized labels defined in your message catalog.

Predefined Catalogs Reference

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

Predefined Catalogs Reference

The github.com/BeamFoundry/rays/pkg/i18n/locales package eliminates boilerplate by providing pre-instantiated singletons for standard locales and pre-registered validation translation functions.

Predefined Locales

The Locales struct contains pre-instantiated Go-Playground Locales singletons for over 200 standard language and territory combinations.

Common Locales

import "github.com/BeamFoundry/rays/pkg/i18n/locales"

// English
locales.Locales.EN // English (base)
locales.Locales.EN_US // English (United States)
locales.Locales.EN_GB // English (United Kingdom)
locales.Locales.EN_CA // English (Canada)
locales.Locales.EN_AU // English (Australia)

// French
locales.Locales.FR // French (base)
locales.Locales.FR_FR // French (France)
locales.Locales.FR_CA // French (Canada)
locales.Locales.FR_BE // French (Belgium)
locales.Locales.FR_CH // French (Switzerland)

// German
locales.Locales.DE // German (base)
locales.Locales.DE_DE // German (Germany)
locales.Locales.DE_AT // German (Austria)
locales.Locales.DE_CH // German (Switzerland)

// Spanish
locales.Locales.ES // Spanish (base)
locales.Locales.ES_ES // Spanish (Spain)
locales.Locales.ES_MX // Spanish (Mexico)

// Other European Languages
locales.Locales.IT // Italian
locales.Locales.PT // Portuguese
locales.Locales.PT_BR // Portuguese (Brazil)
locales.Locales.NL // Dutch
locales.Locales.PL // Polish
locales.Locales.RU // Russian
locales.Locales.UK // Ukrainian

// Asian Languages
locales.Locales.JA // Japanese
locales.Locales.KO // Korean
locales.Locales.ZH // Chinese (Simplified)
locales.Locales.ZH_TW // Chinese (Traditional)
locales.Locales.VI // Vietnamese
locales.Locales.TH // Thai
locales.Locales.ID // Indonesian

// Middle Eastern Languages
locales.Locales.AR // Arabic
locales.Locales.FA // Persian / Farsi
locales.Locales.TR // Turkish

Usage with Message Bundles

Pass any Locales singleton to messageSource.NewMessageBundle() or messageSource.FindMessageBundle():

Prototypes & Foundries

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

Prototypes & Foundries

If you need a new instance of an object every time it is requested (e.g., per HTTP request, per GRPC stream), you cannot use a Singleton. You need a Prototype.

`Foundry[T]`

A Foundry is a type-safe factory automatically provided by the container for any struct marked with Prototype.

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

type SessionState struct {
 Prototype
 userID string
}

// Optional: Initialize state when forged
func (s *SessionState) WithContext(ctx context.Context) Error {
 s.userID = ctx.Value("userID").(string)
 return nil
}

type AuthMiddleware struct {
 Service
 sessionFactory Foundry[*SessionState] `@:"Inject"`
 logger Logging `@:"Inject"`
}

func (m *AuthMiddleware) HandleHTTP(req *http.Request) {
 // 1. Forge a brand new instance
 session, _ := m.sessionFactory.Forge(req.Context())

 // 2. Use the isolated prototype
 m.logger.Info("Handle HTTP connection", "userID", session.userID)
}

6. Testing Framework

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

Testing

Rays eliminates the pain of testing singletons by integrating natively with Ginkgo and Gomega.

Import the testing package and testing suites directly into your test files.

Automatic Container Isolation

The TestingContainer hooks into Ginkgo’s lifecycle. After every It() block, the container is wiped clean. Singletons do not bleed between tests.

Targeted Wiring

By Instead of scanning the whole application, you manually register exactly the Beams you need for the unit under test using AddBeamFor().

BeamFoundry Rays on BeamFoundry Rays Core

1. Introduction

Introduction & Philosophy

Core Principles

Error Handling

Error Handling

Integration with Logging

Message Catalogs & Pluralization

Message Catalogs & Pluralization

Defining Messages in YAML

Complete YAML Example

CLDR Plural Rules

Stereotypes & Beams

Stereotypes & Beams

🧹 Simplifying with Dot Imports

2. Quickstart

Quickstart

📦 Installation

🚀 The Minimal Application

Container Configuration

Container Configuration

1. Defining Configuration Properties

Dependency Injection

Dependency Injection

Basic Injection

Private Field Superiority

Enum Types

Type-Safe Enums

1. Define the Enum Type

Lifecycle Management

Lifecycle Management

Phase 1: Instantiation & Wiring

Web & Template Integration

Web & Template Integration

1. Request-Scoped Locale Management

How It Works

4. Logging Framework

Logging Framework

The Logging Interface

Configuration & Profiles

Configuration & Profiles

1. Binding Data

Localized Struct Validation

Localized Struct Validation

Predefined Catalogs Reference

Predefined Catalogs Reference

Predefined Locales

Common Locales

Usage with Message Bundles

Prototypes & Foundries

Prototypes & Foundries

Foundry[T]

6. Testing Framework

Testing

Automatic Container Isolation

Targeted Wiring

The `Logging` Interface

`Foundry[T]`