Lesson 18: Interceptors and Module Dependencies

ColdBox lifecycle hooks scoped by @scope, and BoxLang module dependencies under modules/.

Interceptors and Module Dependencies

Two smaller, independent conventions round out the picture: lifecycle hooks into the generated ColdBox app, and BoxLang module dependencies your agent needs at runtime.

interceptors/ - ColdBox lifecycle hooks

interceptors/*.bx are ColdBox interceptors (preProcess, postProcess, and other lifecycle hook points), scoped via an @scope annotation on the class itself:

// interceptors/AuditLogger.bx
/**
 * @scope agent
 */
class {

	function preProcess( event, interceptData ) {
		// ...
	}

}

An interceptor with no @scope at all defaults to agent - the narrower, safer choice, since runtime scope has effects beyond one app. An @scope value that isn't agent or runtime fails the build with a clear error.

You've already seen a generated interceptor without writing one yourself - GatewaySessionBootstrap.bx from Lesson 14 and WebUiSchema.bx from Lesson 15 both work exactly this way, just written by BxAgents instead of by you.

modules/ - BoxLang module dependencies

modules/ holds BoxLang module dependencies your agent needs - one immediate subfolder per module, discovered by folder name (not recursive):

modules/
└── my-extra-module/
    ├── module.json
    └── ...

A module folder may include a module.json with a dependsOn array naming other modules/* entries by folder name:

{
	"dependsOn": [ "some-other-module" ]
}

This is BxAgents' own dependency-declaration convention for validation purposes - it's independent of BoxLang's own module-loading mechanism. Circular dependencies are rejected the same way subagent cycles are (see Lesson 11): full cycle path reported, no code generation until the graph is acyclic. A module.json is entirely optional - a module folder with none is assumed to have no declared dependencies.

Try it

Add an interceptors/RequestLogger.bx with an explicit @scope agent annotation that logs every incoming request via writeLog(), rebuild, and check .build/app/interceptors/ for the copy plus its registration in .build/app/config/ColdBox.bx.

Full reference: interceptors/, modules/.

Next: Lesson 19 - Testing Your Agent