SFCC Development MCP Server

# Class Server ## Inheritance Hierarchy - Object - sfra.models.Server ## Description The SFRA Server class is the core routing solution for Salesforce Commerce Cloud's Storefront Reference Architecture (SFRA). This class provides a comprehensive middleware-based routing system that handles HTTP requests, manages route registration, and coordinates the request-response lifecycle. The Server class supports route definition with middleware chains, HTTP method shortcuts (GET/POST), route modification capabilities (prepend/append/replace), and integration with SFCC's hook system for extensibility. It serves as the foundation for all SFRA controller functionality, providing a structured approach to handling web requests with support for caching, personalization, redirects, and various rendering strategies. ## Properties ### routes **Type:** Object Internal registry of all registered routes, indexed by route name. ## Constructor Summary ### Server **Signature:** `Server()` Creates a new Server instance with an empty routes registry. ## Method Summary ### use **Signature:** `use(name, ...middleware) : Route` Creates a new route with middleware chain. ### get **Signature:** `get(name, ...middleware) : Route` Creates a GET-specific route with automatic HTTP method validation. ### post **Signature:** `post(name, ...middleware) : Route` Creates a POST-specific route with automatic HTTP method validation. ### exports **Signature:** `exports() : Object` Returns an exportable object containing all registered routes. ### extend **Signature:** `extend(server) : void` Extends the current server with routes from another server object. ### prepend **Signature:** `prepend(name, ...middleware) : void` Adds middleware to the beginning of an existing route's chain. ### append **Signature:** `append(name, ...middleware) : void` Adds middleware to the end of an existing route's chain. ### replace **Signature:** `replace(name, ...middleware) : void` Replaces an existing route with a new middleware chain. ### getRoute **Signature:** `getRoute(name) : Route` Retrieves a specific route by name. ## Method Detail ### use **Signature:** `use(name, ...middleware) : Route` **Description:** Creates a new route with the specified name and middleware chain. Automatically creates Request and Response objects from global SFCC objects and sets up route completion handling including caching, personalization, and rendering. **Parameters:** - `name` (String) - Unique name for the route - `...middleware` (Function[]) - Variable number of middleware functions to execute **Returns:** Route object representing the created route. **Throws:** - Error if name is not a string - Error if middleware contains non-function items - Error if route name already exists **Route Completion Handling:** - Sets cache expiration based on `res.cachePeriod` and `res.cachePeriodUnit` - Applies personalization with `price_promotion` vary-by header when `res.personalized` is true - Handles redirects with optional status codes - Applies rendering through the render system ### get **Signature:** `get(name, ...middleware) : Route` **Description:** Convenience method for creating GET-only routes. Automatically prepends HTTP GET validation middleware to the chain. **Parameters:** - `name` (String) - Unique name for the route - `...middleware` (Function[]) - Variable number of middleware functions **Returns:** Route object with GET method validation. ### post **Signature:** `post(name, ...middleware) : Route` **Description:** Convenience method for creating POST-only routes. Automatically prepends HTTP POST validation middleware to the chain. **Parameters:** - `name` (String) - Unique name for the route - `...middleware` (Function[]) - Variable number of middleware functions **Returns:** Route object with POST method validation. ### exports **Signature:** `exports() : Object` **Description:** Creates an exportable object containing all registered routes with their public interfaces. Includes internal routes registry for extension capabilities. **Returns:** Object with route names as keys and route interfaces as values, plus `__routes` property containing internal routes. **Export Format:** ```javascript { "routeName": { /* route interface */ }, "__routes": { /* internal routes registry */ } } ``` ### extend **Signature:** `extend(server) : void` **Description:** Extends the current server with routes from another server object created by the `exports()` method. Validates the server object structure before extension. **Parameters:** - `server` (Object) - Server object created by `exports()` method **Throws:** - Error if server object is invalid (missing `__routes`) - Error if server has no routes to extend ### prepend **Signature:** `prepend(name, ...middleware) : void` **Description:** Adds middleware functions to the beginning of an existing route's middleware chain, allowing for route enhancement and modification. **Parameters:** - `name` (String) - Name of existing route to modify - `...middleware` (Function[]) - Middleware functions to prepend **Throws:** - Error if name is not a string - Error if middleware contains non-function items - Error if route does not exist ### append **Signature:** `append(name, ...middleware) : void` **Description:** Adds middleware functions to the end of an existing route's middleware chain, enabling route extension and additional processing. **Parameters:** - `name` (String) - Name of existing route to modify - `...middleware` (Function[]) - Middleware functions to append **Throws:** - Error if name is not a string - Error if middleware contains non-function items - Error if route does not exist ### replace **Signature:** `replace(name, ...middleware) : void` **Description:** Completely replaces an existing route with a new middleware chain, maintaining the same route name but changing implementation. **Parameters:** - `name` (String) - Name of existing route to replace - `...middleware` (Function[]) - New middleware functions for the route **Throws:** - Error if name is not a string - Error if middleware contains non-function items - Error if route does not exist ### getRoute **Signature:** `getRoute(name) : Route` **Description:** Retrieves a specific route object by name for inspection or direct manipulation. **Parameters:** - `name` (String) - Name of the route to retrieve **Returns:** Route object if found, undefined otherwise. ## Route Lifecycle Management ### Route Creation Process 1. **Parameter Validation**: Validates route name and middleware chain 2. **Request/Response Creation**: Creates SFRA Request and Response objects from globals 3. **Route Object Creation**: Instantiates Route with name, middleware, request, and response 4. **Event Handler Registration**: Sets up `route:Complete` event handler 5. **Route Registration**: Stores route in internal registry 6. **Hook Integration**: Calls `app.server.registerRoute` hook if available ### Route Completion Handling **Cache Management:** - Applies cache expiration when `res.cachePeriod` is set - Supports minutes or hours as cache period units (defaults to hours) - Sets HTTP expires header on the response **Personalization:** - Sets `price_promotion` vary-by header when `res.personalized` is true - Enables proper caching behavior for personalized content **Redirect Processing:** - Handles redirect URLs with optional status codes - Emits `route:Redirect` event before redirecting - Supports both default and custom redirect status codes **Rendering Pipeline:** - Applies all accumulated renderings through the render system - Processes ISML templates, JSON responses, XML output, and Page Designer pages ## Integration Points ### Global Object Integration **Request Object Creation:** ```javascript var rq = new Request( typeof request !== 'undefined' ? request : {}, typeof customer !== 'undefined' ? customer : {}, typeof session !== 'undefined' ? session : {} ); ``` **Response Object Creation:** ```javascript var rs = new Response(typeof response !== 'undefined' ? response : {}); ``` ### Hook System Integration The server integrates with SFCC's hook system through the `app.server.registerRoute` hook, allowing: - Custom route event handlers - Route-specific processing extensions - Integration with custom middleware systems ### Middleware Architecture **Middleware Function Signature:** ```javascript function middleware(req, res, next) { // Middleware logic next(); // Continue to next middleware } ``` **Middleware Chain Execution:** - Sequential execution of middleware functions - Support for asynchronous operations through next() callbacks - Automatic error handling and route completion ## Usage Examples ### Basic Route Creation ```javascript server.use('HomePage', function(req, res, next) { res.render('home/homepage', { title: 'Welcome' }); next(); }); ``` ### HTTP Method-Specific Routes ```javascript server.get('ProductShow', middleware.cache, function(req, res, next) { // GET-only route with caching next(); }); server.post('CartAdd', middleware.csrf, function(req, res, next) { // POST-only route with CSRF protection next(); }); ``` ### Route Modification ```javascript // Add authentication to existing route server.prepend('Account-Show', middleware.auth); // Add logging to existing route server.append('Checkout-Begin', middleware.logging); // Replace route implementation server.replace('Search-Show', newSearchMiddleware); ``` ### Server Extension ```javascript // Export routes from one server var exportedRoutes = server.exports(); // Extend another server var newServer = new Server(); newServer.extend(exportedRoutes); ``` ## Error Handling ### Parameter Validation Errors - **Invalid Route Name**: Throws error if first parameter is not a string - **Invalid Middleware**: Throws error if middleware chain contains non-functions - **Duplicate Route**: Throws error if route name already exists ### Extension Errors - **Invalid Server Object**: Throws error for objects missing `__routes` property - **Empty Server**: Throws error when extending with server that has no routes ### Route Modification Errors - **Non-Existent Route**: Throws error when trying to modify routes that don't exist - **Invalid Parameters**: Validates parameters before attempting modifications ## Property Details ### routes **Type:** Object **Description:** Internal registry storing all route definitions indexed by route name. Each entry contains a Route object with the complete middleware chain and configuration. **Structure:** ```javascript { "routeName": Route, // Route object instance "anotherRoute": Route } ``` This registry enables route lookup, modification, and export functionality while maintaining the complete route configuration and state. ---