@horka/app-forge 0.1.0

package/templates/packs/vapor-api/Sources/App/Configure/entrypoint.swift

@@ -0,0 +1,47 @@
+import Vapor
+import Logging
+import Monitoring
+
+@main
+enum Entrypoint {
+    static func main() async throws {
+        var env = try Environment.detect()
+
+        // JSON structured logs in release (one object per line — Loki/Grafana-ready),
+        // human-readable text locally. Level comes from --log / LOG_LEVEL: NEVER hardcoded.
+        if env.isRelease {
+            let level = try Logger.Level.detect(from: &env)
+            LoggingSystem.bootstrap { label in
+                JSONLogHandler(label: label, level: level)
+            }
+        } else {
+            try LoggingSystem.bootstrap(from: &env)
+        }
+
+        let app = try await Application.make(env)
+
+        do {
+            try await configure(app)
+        } catch {
+            app.logger.report(error: error)
+            try? await app.asyncShutdown()
+            throw error
+        }
+        try await app.execute()
+        try await app.asyncShutdown()
+    }
+}
+
+private extension Logger.Level {
+    /// Precedence: --log CLI flag > LOG_LEVEL env var > environment default.
+    static func detect(from environment: inout Environment) throws -> Logger.Level {
+        struct LogSignature: CommandSignature {
+            @Option(name: "log", help: "Change log level")
+            var level: Logger.Level?
+            init() { }
+        }
+        return try LogSignature(from: &environment.commandInput).level
+            ?? Environment.process.LOG_LEVEL
+            ?? (environment == .production ? .notice : .info)
+    }
+}

package/templates/packs/vapor-api/Sources/App/Configure/routes.swift

@@ -0,0 +1,21 @@
+import Fluent
+import Vapor
+import Monitoring
+
+func routes(_ app: Application) throws {
+    // Feature modules — exactly ONE register line per module (auto-registration:
+    // the module's Controllers enum conforms to ControllersRegister).
+    try App.Item.Controllers.register(app: app)
+
+    // Liveness probe for load balancers / uptime monitors.
+    // Unauthenticated by design; excluded from request logs (HTTPLoggingMiddleware).
+    app.get("health") { _ in
+        ["status": "ok"]
+    }
+
+    // Prometheus scrape endpoint — bearer-token gated with a constant-time compare.
+    // Handler lives in the Monitoring target (L1); see docs-architecture/OPS.md.
+    app.get("metrics") { req in
+        try handleMetricsRequest(req)
+    }
+}

package/templates/packs/vapor-api/Sources/App/Error/Failed.swift

@@ -0,0 +1,73 @@
+import Vapor
+
+extension App {
+    /// Typed error contract. Every error this API intentionally returns is a case of one
+    /// of the enums below; the middleware serializes it as `{code, name, description}`.
+    ///
+    /// Rules (see docs-architecture/CONVENTIONS.md):
+    /// - Feature code throws `App.Failed.*` — never raw `Abort`, never string errors.
+    /// - One enum per HTTP status; the case name IS the public error identifier.
+    /// - Keep `convert()` on ONE line — `scripts/generate-error-codes.sh` parses this file
+    ///   to generate `docs/ERROR_CODES.md`. That doc is GENERATED, never hand-written.
+    enum Failed {
+        enum Middlewares {}
+    }
+}
+
+extension App.Failed {
+
+    protocol CustomError: Error {
+        func convert() -> HTTPStatus
+    }
+
+    enum BadRequest: CustomError {
+        case jsonNotDecodable
+        case queryNotFound
+        case pathNotFound
+        case idNotFound
+        case dataNotValid
+
+        func convert() -> HTTPStatus { .badRequest }
+    }
+
+    enum Unauthorized: CustomError {
+        case unauthorized
+
+        func convert() -> HTTPStatus { .unauthorized }
+    }
+
+    enum Forbidden: CustomError {
+        case accessDenied
+
+        func convert() -> HTTPStatus { .forbidden }
+    }
+
+    enum NotFound: CustomError {
+        case dataNotFound
+
+        func convert() -> HTTPStatus { .notFound }
+    }
+
+    enum Conflict: CustomError {
+        case dataAlreadyExist
+
+        func convert() -> HTTPStatus { .conflict }
+    }
+
+    enum InternalServer: CustomError {
+        case jsonNotEncodable
+        case databaseError
+        case unknown
+
+        func convert() -> HTTPStatus { .internalServerError }
+    }
+}
+
+// MARK: - Middlewares
+extension App.Failed.Middlewares: MiddlewaresRegister {
+    static func allCases() -> [any Middleware] {
+        [
+            Handler()
+        ]
+    }
+}

package/templates/packs/vapor-api/Sources/App/Error/FailedMiddleware.swift

@@ -0,0 +1,56 @@
+import Vapor
+import Monitoring
+
+extension App.Failed.Middlewares {
+    /// Converts thrown `App.Failed.CustomError` values into the public error contract:
+    /// HTTP status from `convert()`, JSON body `{code, name, description}`.
+    ///
+    /// `name` is the enum case (stable, machine-matchable by clients); `description` is
+    /// the human-readable status reason. Untyped errors are logged with full context,
+    /// counted, and rethrown so Vapor's ErrorMiddleware formats them — a typed API must
+    /// make untyped errors LOUD, not pretty.
+    struct Handler: AsyncMiddleware {
+        struct ErrorDescription: Codable {
+            let code: UInt
+            let name: String
+            let description: String
+        }
+
+        func respond(to request: Request, chainingTo next: any AsyncResponder) async throws -> Response {
+            do {
+                return try await next.respond(to: request)
+            } catch let error as any App.Failed.CustomError {
+                let status = error.convert()
+
+                recordHTTPError(status: status.code, errorName: "\(error)")
+
+                let payload = ErrorDescription(
+                    code: status.code,
+                    name: "\(error)",
+                    description: status.reasonPhrase
+                )
+
+                do {
+                    let body = try Response.Body(data: JSONEncoder().encode(payload))
+                    var headers = HTTPHeaders()
+                    headers.add(name: .contentType, value: "application/json; charset=utf-8")
+                    return Response(status: status, headers: headers, body: body)
+                } catch {
+                    return Response(status: .internalServerError,
+                                    body: .init(string: "Error encoding error response"))
+                }
+            } catch {
+                request.logger.error("Unhandled error", metadata: [
+                    "error_type": "\(type(of: error))",
+                    "error_description": "\(String(reflecting: error))",
+                    "path": "\(request.url.path)",
+                    "method": "\(request.method.rawValue)",
+                ])
+
+                recordHTTPError(status: 500, errorName: "untyped")
+
+                throw error
+            }
+        }
+    }
+}

package/templates/packs/vapor-api/Sources/App/Features/Item/AppItem.swift

@@ -0,0 +1,38 @@
+import Fluent
+import Vapor
+
+extension App {
+    /// REFERENCE FEATURE MODULE — copy this shape for every new feature.
+    ///
+    /// A feature module is one folder under `Features/` holding everything the feature
+    /// needs, split by role: Controllers (L5), DTO (L5), Services (L3), Entities (L3),
+    /// Repositories (L2), Migrations (L2), Jobs (L2, when needed).
+    ///
+    /// This file is the module's front door: the namespace + its registration surfaces.
+    /// Wiring a feature into the app takes exactly two lines elsewhere:
+    /// - `try App.Item.Controllers.register(app: app)` in Configure/routes.swift
+    /// - `App.Item.Migrations.register(app: app)` in Configure/configure.swift (ORDER MATTERS)
+    enum Item {
+        enum Controllers {}
+        enum Migrations {}
+        enum DTO {}
+    }
+}
+
+// MARK: - Controllers
+extension App.Item.Controllers: ControllersRegister {
+    static func allCases() -> [any RouteCollection] {
+        [
+            Crud()
+        ]
+    }
+}
+
+// MARK: - Migrations
+extension App.Item.Migrations: MigrationsRegister {
+    static func allCases() -> [any Migration] {
+        [
+            Create()
+        ]
+    }
+}

package/templates/packs/vapor-api/Sources/App/Features/Item/Controllers/ItemControllersCrud.swift

@@ -0,0 +1,41 @@
+import Fluent
+import Vapor
+
+extension App.Item.Controllers {
+    /// L5 — HTTP boundary only: decode DTO.Input, call the Service, encode DTO.Output.
+    /// No Fluent queries here, no business rules — if a guard encodes a domain decision,
+    /// it belongs in the Service.
+    struct Crud: RouteCollection {
+        func boot(routes: any RoutesBuilder) throws {
+            let items = routes.grouped("api", "items")
+            items.get(use: index)
+            items.post(use: create)
+            items.get(":itemID", use: get)
+        }
+
+        @Sendable
+        func index(req: Request) async throws -> [App.Item.DTO.Output] {
+            try await App.Item.Service(db: req.db)
+                .list()
+                .map { try App.Item.DTO.Output(entity: $0) }
+        }
+
+        @Sendable
+        func get(req: Request) async throws -> App.Item.DTO.Output {
+            guard let id = req.parameters.get("itemID", as: UUID.self) else {
+                throw App.Failed.BadRequest.idNotFound
+            }
+            let entity = try await App.Item.Service(db: req.db).get(id)
+            return try App.Item.DTO.Output(entity: entity)
+        }
+
+        @Sendable
+        func create(req: Request) async throws -> App.Item.DTO.Output {
+            guard let input = try? req.content.decode(App.Item.DTO.Input.self) else {
+                throw App.Failed.BadRequest.jsonNotDecodable
+            }
+            let entity = try await App.Item.Service(db: req.db).create(name: input.name)
+            return try App.Item.DTO.Output(entity: entity)
+        }
+    }
+}

package/templates/packs/vapor-api/Sources/App/Features/Item/DTO/ItemDTO.swift

@@ -0,0 +1,22 @@
+import Vapor
+
+extension App.Item.DTO {
+    /// Wire types. Entities NEVER serialize directly — the DTO is the public contract,
+    /// the entity is a private persistence detail (renaming a column must not be an
+    /// API-breaking change).
+    struct Input: Content {
+        let name: String
+    }
+
+    struct Output: Content {
+        let id: UUID
+        let name: String
+        let createdAt: Date?
+
+        init(entity: App.Item.Entity) throws {
+            self.id = try entity.requireID()
+            self.name = entity.name
+            self.createdAt = entity.createdAt
+        }
+    }
+}

package/templates/packs/vapor-api/Sources/App/Features/Item/Entities/ItemEntity.swift

@@ -0,0 +1,30 @@
+import Fluent
+import Vapor
+
+extension App.Item {
+    typealias Entities = [Entity]
+
+    /// Fluent model. `@unchecked Sendable` is the Fluent-imposed exception to the
+    /// no-unchecked rule — property wrappers make models mutable reference types.
+    /// CONTAINMENT RULE: an Entity never crosses a concurrency boundary and never leaves
+    /// the request scope — map to DTO.Output at the controller edge
+    /// (docs-architecture/GOTCHAS_LINUX_SWIFT.md).
+    final class Entity: Model, @unchecked Sendable {
+        static let schema = "items"
+
+        @ID(key: .id)
+        var id: UUID?
+
+        @Field(key: "name")
+        var name: String
+
+        @Timestamp(key: "created_at", on: .create)
+        var createdAt: Date?
+
+        init() { }
+
+        init(name: String) {
+            self.name = name
+        }
+    }
+}

package/templates/packs/vapor-api/Sources/App/Features/Item/Migrations/ItemMigrationCreate.swift

@@ -0,0 +1,25 @@
+import Fluent
+
+extension App.Item.Migrations {
+    /// Schema changes are append-only: never edit a shipped migration — add a new one
+    /// (`AddXxx`, `FixXxx`) and list it after this one in AppItem.swift.
+    struct Create: AsyncMigration {
+        typealias Entity = App.Item.Entity
+
+        func prepare(on database: any Database) async throws {
+            try await database.schema(Entity.schema)
+                .id()
+                .field("name", .string, .required)
+                .field("created_at", .datetime)
+                // Name uniqueness is enforced by the DATABASE, not by a check-then-insert in
+                // the service (that read+write is a TOCTOU race under concurrency). The Service
+                // still pre-checks for a clean 409, but this constraint is the source of truth.
+                .unique(on: "name")
+                .create()
+        }
+
+        func revert(on database: any Database) async throws {
+            try await database.schema(Entity.schema).delete()
+        }
+    }
+}

package/templates/packs/vapor-api/Sources/App/Features/Item/Repositories/ItemRepository.swift

@@ -0,0 +1,32 @@
+import Fluent
+import Foundation
+
+extension App.Item {
+    /// L2 — DATA ACCESS ONLY. A repository answers "what does the database say" and
+    /// nothing else: no validation, no normalization, no typed business errors, no
+    /// orchestration. All of that lives in Service (L3). If a method here starts making
+    /// decisions, it is in the wrong layer.
+    struct Repository: Sendable {
+        let db: any Database
+
+        func all() async throws -> Entities {
+            try await Entity.query(on: db)
+                .sort(\.$name)
+                .all()
+        }
+
+        func find(_ id: UUID) async throws -> Entity? {
+            try await Entity.find(id, on: db)
+        }
+
+        func exists(name: String) async throws -> Bool {
+            try await Entity.query(on: db)
+                .filter(\.$name == name)
+                .count() > 0
+        }
+
+        func save(_ entity: Entity) async throws {
+            try await entity.save(on: db)
+        }
+    }
+}

package/templates/packs/vapor-api/Sources/App/Features/Item/Services/ItemService.swift

@@ -0,0 +1,57 @@
+import Fluent
+import FluentKit
+import Foundation
+import {{PROJECT_NAME}}Foundation
+
+extension App.Item {
+    /// L3 — BUSINESS LOGIC for the Item feature. The only layer that makes decisions:
+    /// validation, normalization, typed errors, multi-step orchestration.
+    /// Controllers translate HTTP ↔ DTO and call the service; the repository only
+    /// touches the database. Services never see `Request` — they take plain values,
+    /// which keeps them testable without HTTP.
+    struct Service: Sendable {
+        let repository: Repository
+
+        init(db: any Database) {
+            self.repository = Repository(db: db)
+        }
+
+        func list() async throws -> Entities {
+            try await repository.all()
+        }
+
+        func get(_ id: UUID) async throws -> Entity {
+            guard let entity = try await repository.find(id) else {
+                throw App.Failed.NotFound.dataNotFound
+            }
+            return entity
+        }
+
+        /// Business rules: names are stored trimmed, must not be blank, must be unique.
+        ///
+        /// Uniqueness is enforced by the DB's `.unique(on: "name")` constraint, NOT by the
+        /// pre-check below: `exists` + `save` is a TOCTOU race — two concurrent creates can both
+        /// pass the check and both insert. The pre-check stays only to return a clean 409 on the
+        /// common (uncontended) path; the constraint-failure catch is what makes it correct under
+        /// concurrency, mapping the DB violation to the SAME typed 409.
+        func create(name: String) async throws -> Entity {
+            let cleanName = name.trimmed
+
+            guard !cleanName.isEmpty else {
+                throw App.Failed.BadRequest.dataNotValid
+            }
+            guard try await repository.exists(name: cleanName) == false else {
+                throw App.Failed.Conflict.dataAlreadyExist
+            }
+
+            let entity = Entity(name: cleanName)
+            do {
+                try await repository.save(entity)
+            } catch let error as any DatabaseError where error.isConstraintFailure {
+                // A concurrent insert won the race after our pre-check — same outcome, typed 409.
+                throw App.Failed.Conflict.dataAlreadyExist
+            }
+            return entity
+        }
+    }
+}

package/templates/packs/vapor-api/Sources/App/Registry/ControllersRegister.swift

@@ -0,0 +1,17 @@
+import Vapor
+
+/// Auto-registration surface for a feature module's controllers.
+///
+/// A feature conforms its `Controllers` namespace enum and lists its RouteCollections in
+/// `allCases()`; `routes.swift` then needs exactly ONE line per feature:
+/// `try App.<Feature>.Controllers.register(app: app)`.
+protocol ControllersRegister {
+    static func allCases() -> [any RouteCollection]
+    static func register(app: Application) throws
+}
+
+extension ControllersRegister {
+    static func register(app: Application) throws {
+        try allCases().forEach { try app.register(collection: $0) }
+    }
+}

package/templates/packs/vapor-api/Sources/App/Registry/MiddlewaresRegister.swift

@@ -0,0 +1,15 @@
+import Vapor
+
+/// Auto-registration surface for a feature module's global middlewares.
+/// Used sparingly — most features need none. The typed-error handler (App.Failed) is the
+/// canonical conformer.
+protocol MiddlewaresRegister {
+    static func allCases() -> [any Middleware]
+    static func register(app: Application)
+}
+
+extension MiddlewaresRegister {
+    static func register(app: Application) {
+        allCases().forEach { app.middleware.use($0) }
+    }
+}

package/templates/packs/vapor-api/Sources/App/Registry/MigrationsRegister.swift

@@ -0,0 +1,18 @@
+import Fluent
+import Vapor
+
+/// Auto-registration surface for a feature module's migrations.
+///
+/// `allCases()` order = execution order WITHIN the feature. Order ACROSS features is
+/// decided by the explicit `register` call sequence in `configure.swift` — that ordering
+/// is load-bearing (foreign keys), see docs-architecture/GOTCHAS_LINUX_SWIFT.md.
+protocol MigrationsRegister {
+    static func allCases() -> [any Migration]
+    static func register(app: Application)
+}
+
+extension MigrationsRegister {
+    static func register(app: Application) {
+        allCases().forEach { app.migrations.add($0) }
+    }
+}

package/templates/packs/vapor-api/Sources/Monitoring/Logging/JSONLogHandler.swift

@@ -0,0 +1,59 @@
+import Foundation
+import Logging
+
+/// A LogHandler that writes one JSON object per line to stdout — directly parseable by
+/// Loki/Grafana/CloudWatch. Bootstrapped in `entrypoint.swift` for release builds only;
+/// development keeps Vapor's human-readable text handler.
+public struct JSONLogHandler: LogHandler {
+    public var logLevel: Logger.Level
+    public var metadata: Logger.Metadata = [:]
+
+    private let label: String
+
+    public subscript(metadataKey key: String) -> Logger.Metadata.Value? {
+        get { metadata[key] }
+        set { metadata[key] = newValue }
+    }
+
+    public init(label: String, level: Logger.Level = .info) {
+        self.label = label
+        self.logLevel = level
+    }
+
+    public func log(
+        level: Logger.Level,
+        message: Logger.Message,
+        metadata: Logger.Metadata?,
+        source: String,
+        file: String,
+        function: String,
+        line: UInt
+    ) {
+        var merged = self.metadata
+        if let extra = metadata {
+            merged.merge(extra) { _, new in new }
+        }
+
+        let timestamp = Date().formatted(
+            .iso8601.year().month().day().time(includingFractionalSeconds: true)
+        )
+
+        var dict: [String: String] = [
+            "timestamp": timestamp,
+            "level": level.rawValue,
+            "message": "\(message)",
+            "source": label,
+        ]
+
+        // Metadata becomes flat top-level keys — queryable without JSON-path gymnastics.
+        for (key, value) in merged {
+            dict[key] = "\(value)"
+        }
+
+        if let jsonData = try? JSONSerialization.data(withJSONObject: dict, options: [.sortedKeys]),
+           let jsonString = String(data: jsonData, encoding: .utf8) {
+            // Single fputs call per line: lines never interleave across threads.
+            fputs(jsonString + "\n", stdout)
+        }
+    }
+}

package/templates/packs/vapor-api/Sources/Monitoring/Middleware/HTTPLoggingMiddleware.swift

@@ -0,0 +1,50 @@
+import Vapor
+
+/// Logs every HTTP request with its duration, skipping configured paths.
+/// Replaces Vapor's default RouteLoggingMiddleware to:
+/// - keep noisy probe paths (/metrics, /health) out of the logs
+/// - include response duration in the log metadata
+public struct HTTPLoggingMiddleware: AsyncMiddleware {
+    private let excludedPaths: Set<String>
+
+    public init(excludedPaths: [String] = ["/metrics", "/health"]) {
+        self.excludedPaths = Set(excludedPaths)
+    }
+
+    public func respond(to request: Request, chainingTo next: any AsyncResponder) async throws -> Response {
+        let path = request.url.path
+
+        guard !excludedPaths.contains(path) else {
+            return try await next.respond(to: request)
+        }
+
+        // DispatchTime, not Date: monotonic — wall-clock jumps (NTP) can't produce
+        // negative or absurd durations.
+        let start = DispatchTime.now()
+
+        do {
+            let response = try await next.respond(to: request)
+            let durationMs = Double(DispatchTime.now().uptimeNanoseconds - start.uptimeNanoseconds) / 1_000_000
+
+            request.logger.info("\(request.method) \(path) \(response.status.code)", metadata: [
+                "method": "\(request.method)",
+                "path": "\(path)",
+                "status": "\(response.status.code)",
+                "duration_ms": "\(String(format: "%.1f", durationMs))",
+            ])
+
+            return response
+        } catch {
+            let durationMs = Double(DispatchTime.now().uptimeNanoseconds - start.uptimeNanoseconds) / 1_000_000
+
+            request.logger.error("\(request.method) \(path) ERROR", metadata: [
+                "method": "\(request.method)",
+                "path": "\(path)",
+                "duration_ms": "\(String(format: "%.1f", durationMs))",
+                "error": "\(error)",
+            ])
+
+            throw error
+        }
+    }
+}