Controllers only through services

A controller turns a request into a call and a result into a reply. When it reads storage itself, it skips whatever the service applies on the way (validation, permissions, caching), and every change to the storage layer reaches the HTTP layer. The answer is a rule that lets a controller import other controllers, the services and the shared helpers, and nothing else under src/.

• Plan: plan 0004, Step 5
• Source: the second of the design's three cookbook questions, design § The developer relations hat
• Rule language: rules.md § The four families
• Requirement: FR-REACH-01

The rule

The rule names what a controller may import (pathNot) rather than what it may not, so a new storage folder, a queue client or an HTTP client added next year is covered without editing the rule. Packages from node_modules are not under src/ and stay allowed.

$schema: https://benbahrenburg.github.io/rulebearing/schema/config-v1.json
rules:
  dependencies:
    forbidden:
      - name: controllers-only-through-services
        comment: "A controller that reads storage itself skips the rules the service applies, and every storage change reaches the HTTP layer. plan:0004-wave-4-reach"
        fix: "Call a function in src/services/ instead; if none fits, add one there that wraps the repository call."
        severity: error
        from: { path: "^src/controllers/" }
        to: { path: "^src/", pathNot: "^src/(controllers|services|shared)/" }
        examples:
          forbidden:
            - "src/controllers/report-controller.ts -> src/repositories/order-repository.ts"
          allowed:
            - "src/controllers/order-controller.ts -> src/services/order-service.ts"
            - "src/controllers/order-controller.ts -> src/shared/http.ts"
            - "src/services/order-service.ts -> src/repositories/order-repository.ts"

The file is rulebearing.yaml. Its examples are the edges rulebearing test checks the rule against.

The same rule for dependency-cruiser

rulebearing config convert rulebearing.yaml --to dependency-cruiser writes the rule in dependency-cruiser's format and names what it dropped: the $schema, the fix and the examples.

{
  "forbidden": [
    {
      "name": "controllers-only-through-services",
      "comment": "A controller that reads storage itself skips the rules the service applies, and every storage change reaches the HTTP layer. plan:0004-wave-4-reach",
      "to": {
        "path": "^src/",
        "pathNot": "^src/(controllers|services|shared)/"
      },
      "severity": "error",
      "from": {
        "path": "^src/controllers/"
      }
    }
  ]
}

dropped 3 item(s) dependency-cruiser cannot hold:
  $schema: points at the native schema
  forbidden[controllers-only-through-services].fix: a Rulebearing rule field
  forbidden[controllers-only-through-services].examples: a Rulebearing rule field

The files are converted/.dependency-cruiser.json and converted/dropped.txt.

The failing edge

In repo/, src/controllers/order-controller.ts goes through src/services/order-service.ts, but src/controllers/report-controller.ts sums the orders straight from the repository:

• controllers-only-through-services fix: Call a function in src/services/ instead; if none fits, add one there that wraps the repository call.

The fix

The service already has the function the report controller computes by hand. Call it:

// src/controllers/report-controller.ts
import { ok } from '../shared/http';
import type { Reply } from '../shared/http';
import { revenueCents } from '../services/order-service';

export function getRevenue(): Reply {
  return ok({ cents: revenueCents() });
}

When no service function fits, add one to src/services/ that wraps the repository call, so the next controller finds it there.

Try it

The playground holds this page's repository and rule. Run cruises the files in this browser, as rulebearing cruise does in repo/; change the rule and run it again, or pick another output type.