ColdBox Platform

ColdBox is part of a larger ecosystem of standalone-compatible libraries and extended modules. You can use the core libraries in any BoxLang/CFML application, or use the specialized modules to extend ColdBox functionality.

Core Libraries (Standalone Compatible)

• WireBox DI: Dependency injection for BoxLang/CFML.
• CacheBox: Enterprise caching for BoxLang/CFML.
• LogBox: Structured logging for BoxLang/CFML.

Extended Ecosystem Modules

• CB Security: Enterprise security framework.
• CB Rest: REST API development.
• CB Validation: Server-side validation.
• CB ORM: ORM enhancements.

All modules and libraries can be discovered via ForgeBox.io.

LogBox uses a modular architecture consisting of several core components:

• LogBox: The central factory and configuration manager.
• Logger: Individual instances that provide category-based control (e.g., MyApp.Database).
• Appenders: The output destinations where logs are sent (e.g., File, Console, Database, Email).
• Layouts: Responsible for formatting the log message structure (e.g., Simple, JSON, XML).
• Filters: Used for routing or filtering log entries before they reach appenders.

Tier 2 is used for handlers that cannot or should not use Event Caching (e.g., content that is highly user-specific but still benefits from client-side conditional-GET).

How it works:

1. The handler and the full render process still run on every request.
2. After rendering is complete, the framework computes a hash of the body.
3. It compares this hash against the client's If-None-Match header.
4. If they match, it sends a 304 Not Modified to save the client from downloading the body.

Warning: Unlike Tier 1, Tier 2 does not save server-side resources; the server still performs the full execution and rendering. Do not enable this on expensive endpoints expecting the same performance gains as Event Caching.

// Tier 2: etag is true, but cache is NOT true
function show( event, rc, prc )
    etag="true"
{
    ...
}

ColdBox provides specific interception points during the SSE lifecycle. You can use these to implement authentication, rate limiting, or connection monitoring.

Interception Points:

• preSSEConnection: Triggered before the stream opens. It receives { options }.
  • To Reject: Return true. You can then set a custom status via event.setHTTPHeader( statusCode = 429 ) or render a standard error view/layout. If you do nothing, ColdBox returns a 403 Forbidden.
• postSSEConnection: Triggered after the connection is established. It receives { sentCount, duration }. Useful for metrics and accounting.
• onSSEError: Triggered if an exception occurs inside the callback. It receives { exception, sentCount }. Useful for logging and alerting.

ColdBox is built as a cohesive platform consisting of four primary integrated subsystems:

1. ColdBox MVC Core: Handles HMVC architecture, routing, and the event-driven request lifecycle.
2. WireBox: The Dependency Injection (IoC) container providing object lifecycle management and AOP.
3. CacheBox: An enterprise caching engine supporting multi-provider and distributed caching.
4. LogBox: A structured logging framework with multiple appender support.

Standalone Usage: A key architectural feature is that WireBox, CacheBox, and LogBox are designed as standalone libraries. You can install and use them independently in any BoxLang or CFML application without the full ColdBox framework.

ColdBox uses two distinct mechanisms for executing code during the request lifecycle:

1. Interceptors (InterceptorState.cfc): These are global or module-scoped. They run in an ordered chain. An interceptor can short-circuit the chain by returning true. They are ideal for cross-cutting concerns like authentication, logging, or global security headers.

2. Route Middleware (RoutingService.runRouteMiddleware()): These are attached specifically to routes via the Router.cfc. They run at the preProcess or postProcess boundaries of the matched route, positioned "closest to the handler" and inside the global interceptor chain. They are ideal for logic that only applies to specific URL patterns or resource groups.

The Provider pattern allows for lazy loading of services. Instead of injecting the service directly, you inject a provider. The actual service is only instantiated and retrieved when you call the .get() method on the provider.

class {
    @inject( "provider:UserService" )
    property userServiceProvider;

    function getUser( id ) {
        // Service is created only when needed
        var userService = userServiceProvider.get()
        return userService.findById( arguments.id )
    }
}

Tier 1 provides a 'free win' by combining ColdBox Event Caching with automatic ETag generation. When you enable both via annotations, the system hashes the response body during the initial cache write. On subsequent requests within the cache window, if the client's If-None-Match header matches the stored hash, the system returns a 304 Not Modified without executing the handler or rendering the view.

function index( event, rc, prc )
    cache="true"
    cacheTimeout="300"
    etag="true"
{
    prc.products = productService.list()
    event.setView( "products/index" )
}