3. IoC Container on BeamFoundry Rays Core

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.

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.

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.

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.

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)
}