feat: (W-005) Interface-driven design contracts for Wheels 4.0

vendor/wheels/Bindings.cfc

@@ -5,10 +5,53 @@
 component {
 
 	public void function configure(required any injector) {
+		// Core framework components
 		arguments.injector
 			.map("global").to("wheels.Global")
 			.map("eventmethods").to("wheels.events.EventMethods")
 			.map("ViewObj").to("wheels.view");
+
+		// Interface → default implementation bindings
+		// These enable community drop-in replacements via:
+		//   bind("ModelFinderInterface").to("my.CustomFinder")
+
+		// Model subsystem
+		arguments.injector
+			.bind("ModelFinderInterface").to("wheels.model.read")
+			.bind("ModelPersistenceInterface").to("wheels.model.create")
+			.bind("ModelValidationInterface").to("wheels.model.validations")
+			.bind("ModelErrorInterface").to("wheels.model.errors")
+			.bind("ModelCallbackInterface").to("wheels.model.callbacks")
+			.bind("ModelAssociationInterface").to("wheels.model.associations")
+			.bind("ModelPropertyInterface").to("wheels.model.properties");
+
+		// Controller subsystem
+		arguments.injector
+			.bind("ControllerFilterInterface").to("wheels.controller.filters")
+			.bind("ControllerRenderingInterface").to("wheels.controller.rendering")
+			.bind("ControllerFlashInterface").to("wheels.controller.flash");
+
+		// View subsystem
+		arguments.injector
+			.bind("ViewFormInterface").to("wheels.view.formsplain")
+			.bind("ViewLinkInterface").to("wheels.view.links")
+			.bind("ViewContentInterface").to("wheels.view.miscellaneous");
+
+		// Routing subsystem
+		arguments.injector
+			.bind("RouteMapperInterface").to("wheels.Mapper")
+			.bind("RouteResolverInterface").to("wheels.Mapper");
+
+		// Events subsystem
+		arguments.injector
+			.bind("EventHandlerInterface").to("wheels.events.EventMethods");
+
+		// Database adapters (no default — adapter is selected per datasource at runtime)
+		// Bind per-project: bind("DatabaseModelAdapterInterface").to("wheels.databaseAdapters.H2.H2Model")
+
+		// DI subsystem
+		arguments.injector
+			.bind("InjectorInterface").to("wheels.Injector");
 	}
 
 }

vendor/wheels/Injector.cfc

@@ -11,7 +11,7 @@
  *
  * Self-registers at application.wheelsdi for framework-wide access.
  */
-component {
+component implements="wheels.interfaces.di.InjectorInterface" {
 
 	/**
 	 * Constructor. Accepts a dotted-path to a Bindings CFC that has a configure(injector) method.

vendor/wheels/events/EventMethods.cfc

@@ -1,4 +1,4 @@
-component extends="wheels.Global" {
+component extends="wheels.Global" implements="wheels.interfaces.events.EventHandlerInterface" {
 	public string function $runOnError(required exception, required eventName) {
 		if (StructKeyExists(application, "wheels") && StructKeyExists(application.wheels, "initialized")) {
 			$restoreTestRunnerApplicationScope();

vendor/wheels/interfaces/AuthStrategy.cfc

@@ -0,0 +1,11 @@
+/**
+ * Re-export of `wheels.auth.AuthStrategy` for the central interface catalog.
+ *
+ * The canonical interface lives at `wheels.auth.AuthStrategy`.
+ * This wrapper provides access via the `wheels.interfaces` namespace.
+ *
+ * [section: Authentication]
+ * [category: Interface]
+ */
+interface extends="wheels.auth.AuthStrategy" {
+}

vendor/wheels/interfaces/AuthenticatorInterface.cfc

@@ -0,0 +1,11 @@
+/**
+ * Re-export of `wheels.auth.AuthenticatorInterface` for the central interface catalog.
+ *
+ * The canonical interface lives at `wheels.auth.AuthenticatorInterface`.
+ * This wrapper provides access via the `wheels.interfaces` namespace.
+ *
+ * [section: Authentication]
+ * [category: Interface]
+ */
+interface extends="wheels.auth.AuthenticatorInterface" {
+}

vendor/wheels/interfaces/MiddlewareInterface.cfc

@@ -0,0 +1,12 @@
+/**
+ * Re-export of `wheels.middleware.MiddlewareInterface` for the central interface catalog.
+ *
+ * The canonical interface lives at `wheels.middleware.MiddlewareInterface`.
+ * This wrapper provides access via the `wheels.interfaces` namespace without
+ * breaking existing `implements="wheels.middleware.MiddlewareInterface"` references.
+ *
+ * [section: Middleware]
+ * [category: Interface]
+ */
+interface extends="wheels.middleware.MiddlewareInterface" {
+}

vendor/wheels/interfaces/ServiceProviderInterface.cfc

@@ -0,0 +1,11 @@
+/**
+ * Re-export of `wheels.ServiceProviderInterface` for the central interface catalog.
+ *
+ * The canonical interface lives at `wheels.ServiceProviderInterface`.
+ * This wrapper provides access via the `wheels.interfaces` namespace.
+ *
+ * [section: Plugins]
+ * [category: Interface]
+ */
+interface extends="wheels.ServiceProviderInterface" {
+}

vendor/wheels/interfaces/controller/ControllerFilterInterface.cfc

@@ -0,0 +1,47 @@
+/**
+ * Contract for controller filter chain (before/after action hooks).
+ *
+ * The default implementation lives in `wheels.controller.filters` and is mixed
+ * into Controller instances at runtime. Compliance is verified by runtime reflection tests.
+ *
+ * Filters are registered in a controller's `config()` method and run before
+ * or after the matching action executes.
+ *
+ * [section: Controller]
+ * [category: Interface]
+ */
+interface {
+
+	/**
+	 * Register a filter to run before or after controller actions.
+	 *
+	 * @through Comma-delimited list of method names to call.
+	 * @type Filter type: "before" or "after".
+	 * @only Comma-delimited list of actions this filter applies to (whitelist).
+	 * @except Comma-delimited list of actions to skip (blacklist).
+	 * @placement Where to insert: "prepend" or "append" (default).
+	 */
+	public void function filters(
+		string through,
+		string type,
+		string only,
+		string except,
+		string placement
+	);
+
+	/**
+	 * Return the current filter chain as an array of structs.
+	 *
+	 * @type Filter type to return: "before", "after", or blank for all.
+	 * @return Array of filter configuration structs.
+	 */
+	public array function filterChain(string type);
+
+	/**
+	 * Replace the entire filter chain with the given array.
+	 *
+	 * @chain Array of filter configuration structs.
+	 */
+	public void function setFilterChain(array chain);
+
+}

vendor/wheels/interfaces/controller/ControllerFlashInterface.cfc

@@ -0,0 +1,65 @@
+/**
+ * Contract for controller flash message storage (session-based one-time messages).
+ *
+ * The default implementation lives in `wheels.controller.flash` and is mixed
+ * into Controller instances at runtime. Compliance is verified by runtime reflection tests.
+ *
+ * Flash messages persist for exactly one request (typically across a redirect).
+ *
+ * [section: Controller]
+ * [category: Interface]
+ */
+interface {
+
+	/**
+	 * Return the flash value for the given key.
+	 *
+	 * @key The flash key to retrieve.
+	 * @return The stored value, or an empty string if not found.
+	 */
+	public any function flash(string key);
+
+	/**
+	 * Insert one or more key/value pairs into the flash.
+	 * Pass keys as named arguments: `flashInsert(success="Record saved")`.
+	 */
+	public void function flashInsert();
+
+	/**
+	 * Clear all flash messages.
+	 */
+	public void function flashClear();
+
+	/**
+	 * Return the number of flash messages currently stored.
+	 */
+	public numeric function flashCount();
+
+	/**
+	 * Delete a specific flash key and return its value.
+	 *
+	 * @key The flash key to delete.
+	 * @return The value that was stored under the key.
+	 */
+	public any function flashDelete(required string key);
+
+	/**
+	 * Return true if the flash is empty.
+	 */
+	public boolean function flashIsEmpty();
+
+	/**
+	 * Keep flash messages for one additional request (prevent auto-clear).
+	 *
+	 * @key Specific key to keep, or blank for all keys.
+	 */
+	public void function flashKeep(string key);
+
+	/**
+	 * Return true if the given key exists in the flash.
+	 *
+	 * @key The flash key to check.
+	 */
+	public boolean function flashKeyExists(string key);
+
+}

vendor/wheels/interfaces/controller/ControllerRenderingInterface.cfc

@@ -0,0 +1,147 @@
+/**
+ * Contract for controller rendering and response generation.
+ *
+ * The default implementation lives in `wheels.controller.rendering` and is mixed
+ * into Controller instances at runtime. Compliance is verified by runtime reflection tests.
+ *
+ * [section: Controller]
+ * [category: Interface]
+ */
+interface {
+
+	/**
+	 * Render a view template and return or set it as the response.
+	 *
+	 * @controller Controller name (default: current controller).
+	 * @action Action/view name (default: current action).
+	 * @template Path to a specific template file.
+	 * @layout Layout to wrap the view in (false to skip layout).
+	 * @cache Minutes to cache the rendered output.
+	 * @returnAs "string" to return the output instead of setting it as the response.
+	 * @hideDebugInformation Suppress debug output.
+	 * @status HTTP status code.
+	 */
+	public any function renderView(
+		string controller,
+		string action,
+		string template,
+		any layout,
+		any cache,
+		string returnAs,
+		boolean hideDebugInformation,
+		numeric status
+	);
+
+	/**
+	 * Render a partial template.
+	 *
+	 * @partial Path to the partial (e.g., "comments/comment").
+	 * @cache Minutes to cache.
+	 * @layout Layout to wrap the partial in.
+	 * @returnAs "string" to return instead of setting as response.
+	 * @dataFunction Function name that provides data to the partial.
+	 * @status HTTP status code.
+	 */
+	public any function renderPartial(
+		string partial,
+		any cache,
+		any layout,
+		string returnAs,
+		any dataFunction,
+		numeric status
+	);
+
+	/**
+	 * Render a plain text string as the response.
+	 *
+	 * @text The text content.
+	 * @status HTTP status code.
+	 */
+	public void function renderText(string text, any status);
+
+	/**
+	 * Render an empty response body.
+	 *
+	 * @status HTTP status code (default: 200).
+	 */
+	public void function renderNothing(string status);
+
+	/**
+	 * Render data using a format-appropriate template (JSON, XML, etc.).
+	 *
+	 * @data The data to render (query, struct, array, or object).
+	 * @controller Controller name.
+	 * @action Action name.
+	 * @template Template path.
+	 * @layout Layout.
+	 * @cache Minutes to cache.
+	 * @returnAs "string" to return instead of setting as response.
+	 * @hideDebugInformation Suppress debug output.
+	 * @status HTTP status code.
+	 */
+	public any function renderWith(
+		any data,
+		string controller,
+		string action,
+		string template,
+		any layout,
+		any cache,
+		string returnAs,
+		boolean hideDebugInformation,
+		numeric status
+	);
+
+	/**
+	 * Redirect the client to another URL or route.
+	 *
+	 * @back If true, redirect to the HTTP referrer (ignores other routing params).
+	 * @controller Target controller.
+	 * @action Target action.
+	 * @route Named route.
+	 * @method HTTP method override for the redirect target.
+	 * @key Primary key value for the route.
+	 * @params Additional URL parameters as a struct or string.
+	 * @anchor URL fragment anchor.
+	 * @onlyPath Whether to generate a relative path (true) or full URL (false).
+	 * @host Override host for the URL.
+	 * @protocol Override protocol (http/https).
+	 * @port Override port.
+	 * @statusCode HTTP redirect status code (301, 302, etc.).
+	 * @addToken Whether to add session token (CF-specific).
+	 * @url Explicit external URL to redirect to (bypasses route generation).
+	 * @delay Whether to delay the redirect until after the action completes.
+	 * @encode Whether to encode the URL.
+	 */
+	public void function redirectTo(
+		boolean back,
+		string controller,
+		string action,
+		string route,
+		string method,
+		any key,
+		any params,
+		string anchor,
+		boolean onlyPath,
+		string host,
+		string protocol,
+		numeric port,
+		numeric statusCode,
+		boolean addToken,
+		string url,
+		boolean delay,
+		boolean encode
+	);
+
+	/**
+	 * Return the current response body.
+	 */
+	public string function response();
+
+	/**
+	 * Set the response body directly.
+	 *
+	 * @content The response content string.
+	 */
+	public void function setResponse(string content);
+
+}