@lakutata/template-service 3.0.0-beta.0

package/LICENSE

@@ -0,0 +1,23 @@
+MIT License
+
+Copyright (c) 2023-present Lakutata
+
+All rights reserved
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,9 @@
+# @lakutata/template-service
+
+The service template of the [lakutata](https://github.com/lakutata/lakutata) projects: an HTTP API, deployed as a Docker
+image. The project is a workspace whose `app` package is the service; other packages (a client SDK…) are added next to
+it.
+
+```bash
+npx @lakutata/cli create --name my-service --template service
+```

package/features/i18n/packages/app/package.json

@@ -0,0 +1,6 @@
+{
+  "scripts": {
+    "i18n:check": "lakutata i18n check --dir src/locales",
+    "i18n:types": "lakutata i18n types --dir src/locales"
+  }
+}

package/features/i18n/packages/app/src/locales/en.json

@@ -0,0 +1,5 @@
+{
+  "greeting": {
+    "hello": "Hello, {name}!"
+  }
+}

package/features/i18n/packages/app/src/locales/zh-CN.json

@@ -0,0 +1,5 @@
+{
+  "greeting": {
+    "hello": "你好，{name}！"
+  }
+}

package/features/installer/Dockerfile.installer

@@ -0,0 +1,10 @@
+# The installers of Linux (npm run package:linux), made on Linux: the packages of the configuration (lakutata.installer
+# of the package.json) in dist/installer. The ones of another architecture: docker buildx build --platform linux/amd64 ...
+# The apk packages are made on Alpine (node:22-alpine), with Bun when the application has native addons.
+FROM node:22-bookworm AS build
+WORKDIR /project
+COPY . .
+RUN (npm ci --no-audit --no-fund || npm install --no-audit --no-fund) && npm run build && npm run package -w app -- --outdir /installer
+
+FROM scratch
+COPY --from=build /installer /

package/features/installer/package.json

@@ -0,0 +1,9 @@
+{
+  "scripts": {
+    "package:host": "npm run build && npm run package -w app -- --outdir ../../dist/installer",
+    "package:linux": "docker buildx build --file Dockerfile.installer --output type=local,dest=dist/installer ."
+  },
+  "devDependencies": {
+    "@lakutata/builder": "^{$LAKUTATA_VERSION}"
+  }
+}

package/features/installer/packages/app/package.json

@@ -0,0 +1,26 @@
+{
+  "bin": {
+    "{$APP_ID}": "build/App.js"
+  },
+  "scripts": {
+    "package": "lakutata package installer"
+  },
+  "lakutata": {
+    "icon": "../resources/logo.png",
+    "installer": {
+      "name": "{$APP_ID}",
+      "service": {
+        "env": {
+          "PORT": "8080"
+        }
+      },
+      "linux": {
+        "targets": [
+          "deb",
+          "rpm",
+          "tar.gz"
+        ]
+      }
+    }
+  }
+}

package/features/installer/packages/resources/package.json

@@ -0,0 +1,6 @@
+{
+  "name": "resources",
+  "version": "0.0.1",
+  "private": true,
+  "description": "The resources of the application: its icon (logo.png, lakutata.icon of the app package), made into the icons of each platform"
+}

package/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "@lakutata/template-service",
+  "version": "3.0.0-beta.0",
+  "description": "The service template of the lakutata projects: an HTTP API deployed as a Docker image.",
+  "keywords": [
+    "lakutata",
+    "lakutata-template"
+  ],
+  "license": "MIT",
+  "files": [
+    "template",
+    "features",
+    "README.md",
+    "LICENSE"
+  ],
+  "lakutata": {
+    "template": "service",
+    "features": {
+      "i18n": "The messages in several languages (lakutata/com/i18n): src/locales, the language of each request",
+      "installer": "The installers of the application (lakutata package installer): deb, rpm and tar.gz on Linux (npm run package:linux in Docker), pkg and tar.gz on macOS, nsis, msi and zip on Windows, its service registered (systemd, launchd, WinSW), its program in the PATH"
+    }
+  }
+}

package/template/Dockerfile

@@ -0,0 +1,18 @@
+# The build: the dependencies and the sources, compiled
+FROM node:22-alpine AS build
+WORKDIR /project
+COPY . .
+RUN npm ci --no-audit --no-fund && npm run build && npm prune --omit=dev
+
+# The image: the compiled service and its production dependencies, run by an unprivileged user
+FROM node:22-alpine
+ENV NODE_ENV=production PORT=8080
+WORKDIR /project
+COPY --from=build --chown=node:node /project /project
+USER node
+EXPOSE 8080
+# Whether the process answers: the dependencies (database, message broker) are not part of it, the service stays up
+# while they recover
+HEALTHCHECK --interval=30s --timeout=5s --start-period=20s --retries=3 \
+    CMD node -e "fetch('http://127.0.0.1:'+process.env.PORT+'/health').then(r=>process.exit(r.ok?0:1),()=>process.exit(1))"
+CMD ["node", "packages/app/build/App.js"]

package/template/README.md

@@ -0,0 +1,71 @@
+# {$APP_NAME}
+
+{$APP_DESC}
+
+A [lakutata](https://github.com/lakutata/lakutata) service. The project is a workspace: `packages/app` is the service;
+the other packages (a client SDK…) are added in `packages/`.
+
+```bash
+npm run dev            # build and start the service, http://localhost:8080/example
+npm test               # build the packages and run their tests
+npm run build          # build the packages, in the order of their dependencies
+npm run version:patch  # give the packages their next version
+npm run docker:build   # build the image {$APP_ID}:<version>
+DOCKER_REPOSITORY=registry.example.com/team/{$APP_ID} npm run docker:push   # build it for linux/amd64 and push it
+```
+
+The results are `{errno, errMsg, data}`, the errors too (with the status 200). The requests carry
+`Authorization: Bearer <API_TOKEN>` when the environment has an `API_TOKEN`
+(`packages/app/src/middlewares/Authenticate.ts`). `/health` tells whether the process answers.
+
+`docker login <registry>` once before pushing: the credentials are kept by Docker.
+
+<!-- @if installer -->
+## The installers
+
+`npm run package:host` makes the installers of the platform it runs on (`lakutata package installer`, configured by the
+`lakutata.installer` of `packages/app/package.json`) in `dist/installer`: the application, its command
+`{$APP_ID}` in the PATH, and its service started at the start of the system, with its environment (`PORT`, `MODE`…, kept by
+the upgrades) and its data:
+
+- Linux: the deb, rpm and tar.gz packages; the application in `/opt/{$APP_ID}`, its service run by systemd, its environment
+  `/etc/{$APP_ID}/{$APP_ID}.env` (`systemctl restart {$APP_ID}` after changing it), its data `/var/lib/{$APP_ID}`.
+  `npm run package:linux` makes them in Docker (`Dockerfile.installer`, in `dist/installer`) on any platform.
+- macOS: the pkg package; the application in `/usr/local/lib/{$APP_ID}`, its service run by launchd, its environment
+  `/usr/local/etc/{$APP_ID}/{$APP_ID}.env` (`sudo /usr/local/lib/{$APP_ID}/uninstall` removes it).
+- Windows: the installer of NSIS and the package of Windows Installer (msi); the application in
+  `C:\Program Files\{$APP_ID}`, its service run by WinSW, its environment `C:\ProgramData\{$APP_ID}\{$APP_ID}.env`
+  (`Restart-Service {$APP_ID}` after changing it).
+
+<!-- @end -->
+## Database migrations
+
+```bash
+npm run migration:generate              # the migrations of the changes of the entities of the databases
+npm run migration:create -- seed-users  # an empty migration, written by hand
+npm run migration:show                  # the migrations run [X] and pending [ ]
+npm run migration:run                   # run the pending migrations
+npm run migration:revert                # revert the last migration run
+```
+
+The commands (`lakutata migration <action>`) build and start the service, which connects its databases with their
+options (without synchronizing their schemas), does the command and exits; `-- --database <name>` selects a database
+(required to revert when there are several), `-- --fake` marks the migrations as run or reverted without executing
+them. The migrations are written into `packages/app/src/migrations`, compiled with the service and given to the options of the
+databases, run when they connect:
+
+```typescript
+import {buildDatabaseOptions} from 'lakutata/com/database'
+import {Migrations1788773616343} from '../migrations/1788773616343-db.js'
+
+components: {
+    db: buildDatabaseOptions({
+        type: 'postgres',
+        url: process.env.DATABASE_URL,
+        entities: [/* the entities */],
+        synchronize: false,
+        migrationsRun: true,
+        migrations: [Migrations1788773616343]
+    })
+}
+```

package/template/_dockerignore

@@ -0,0 +1,10 @@
+.git
+node_modules
+**/node_modules
+**/build
+*.log
+.env
+.env.*
+**/.next
+**/.nuxt
+**/.output

package/template/_gitignore

@@ -0,0 +1,13 @@
+node_modules
+build
+dist
+*.log
+.env
+.env.*
+.DS_Store
+.idea
+.vscode
+.next
+next-env.d.ts
+.nuxt
+.output

package/template/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "{$APP_ID}-workspace",
+  "version": "0.0.1",
+  "private": true,
+  "workspaces": [
+    "packages/*"
+  ],
+  "scripts": {
+    "build": "lakutata run rebuild",
+    "test": "lakutata run test",
+    "dev": "lakutata run dev --parallel",
+    "migration:generate": "lakutata migration generate --package app",
+    "migration:create": "lakutata migration create --package app",
+    "migration:run": "lakutata migration run --package app",
+    "migration:revert": "lakutata migration revert --package app",
+    "migration:show": "lakutata migration show --package app",
+    "start": "npm start -w app",
+    "version:patch": "lakutata version patch --yes",
+    "docker:build": "docker buildx build --tag {$APP_ID}:$npm_package_version --load .",
+    "docker:push": "docker buildx build --platform linux/amd64 --tag $DOCKER_REPOSITORY:$npm_package_version --tag $DOCKER_REPOSITORY:latest --push ."
+  },
+  "devDependencies": {
+    "@lakutata/cli": "^{$LAKUTATA_VERSION}",
+    "@types/node": "^22.0.0",
+    "typescript": "^6.0.3"
+  },
+  "engines": {
+    "node": ">=22"
+  }
+}

package/template/packages/app/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "app",
+  "version": "0.0.1",
+  "description": "{$APP_DESC}",
+  "author": "{$APP_AUTHOR}",
+  "license": "{$APP_LICENSE}",
+  "private": true,
+  "type": "module",
+  "main": "build/App.js",
+  "scripts": {
+    "clean": "lakutata clean",
+    "build": "tsc",
+    "rebuild": "npm run clean && npm run build",
+    "dev": "npm run rebuild && node build/App.js",
+    "start": "node build/App.js",
+    "test": "node --test \"build/tests/**/*.spec.js\""
+  },
+  "dependencies": {
+    "compression": "^1.8.1",
+    "express": "^5.2.1",
+    "lakutata": "^{$LAKUTATA_VERSION}"
+  },
+  "devDependencies": {
+    "@types/compression": "^1.8.1",
+    "@types/express": "^5.0.6"
+  }
+}

package/template/packages/app/src/App.ts

@@ -0,0 +1,7 @@
+import {Application, type ILogger} from 'lakutata'
+import {installerConfig} from './config/Config.js'
+
+Application
+    .run(installerConfig)
+    .onLaunched((app: Application, log: ILogger): void => log.info('%s started in %s mode', app.appName, app.mode()))
+    .onFatalException((error: Error, log: ILogger): void => log.error('The service cannot start: %s', error.message))

package/template/packages/app/src/config/Config.ts

@@ -0,0 +1,47 @@
+import type {ApplicationOptions} from 'lakutata'
+import {buildEntrypoints} from 'lakutata/com/entrypoint'
+import {expressHTTPEntrypoint, jsonEnvelope} from 'lakutata/adapter/express'
+import compression from 'compression'
+import {authenticate} from '../middlewares/Authenticate.js'
+import {ExampleController} from '../controllers/ExampleController.js'
+import {HealthController} from '../controllers/HealthController.js'
+//@if i18n
+import {buildI18nOptions, I18nMiddleware} from 'lakutata/com/i18n'
+import en from '../locales/en.json' with {type: 'json'}
+import zhCN from '../locales/zh-CN.json' with {type: 'json'}
+//@end
+
+/**
+ * The options of the service
+ * @param port the port of the HTTP server, the PORT environment variable or 8080 by default
+ */
+export function installerConfig(port: number = Number(process.env.PORT ?? 8080)): ApplicationOptions {
+    return {
+        id: '{$APP_ID}',
+        name: '{$APP_NAME}',
+        mode: process.env.NODE_ENV === 'production' ? 'production' : 'development',
+        components: {
+            //@if i18n
+            //The messages of the languages (src/locales), bundled with the code; created by the first request
+            i18n: buildI18nOptions({messages: {'en': en, 'zh-CN': zhCN}}),
+            //@end
+            entrypoint: buildEntrypoints({
+                controllers: [HealthController, ExampleController],
+                //@if i18n
+                //The messages in the language of each request: ?lang=, the cookie lang, Accept-Language
+                middlewares: [I18nMiddleware],
+                //@end
+                http: expressHTTPEntrypoint({
+                    port: port,
+                    //The results and the errors are {errno, errMsg, data}, with the status 200
+                    respond: jsonEnvelope({errorStatus: 200}),
+                    body: {limit: '100mb'},
+                    server: {keepAliveTimeout: 60000, headersTimeout: 65000},
+                    middlewares: [authenticate],
+                    before: (app): void => void app.use(compression())
+                })
+            })
+        },
+        bootstrap: ['entrypoint']
+    }
+}

package/template/packages/app/src/controllers/ExampleController.ts

@@ -0,0 +1,32 @@
+import {Controller} from 'lakutata/com/entrypoint'
+import {GET, Prefix} from 'lakutata/decorator/ctrl'
+import {GreetDTO} from '../dtos/GreetDTO.js'
+//@if i18n
+import {Inject} from 'lakutata/decorator/di'
+import {Translator} from 'lakutata/com/i18n'
+//@end
+
+@Prefix({route: '/example'})
+export class ExampleController extends Controller {
+    //@if i18n
+
+    /**
+     * The messages of the language of the request
+     */
+    @Inject(Translator)
+    protected readonly i18n: Translator
+    //@end
+
+    /**
+     * GET /example?name=you
+     * @param input
+     */
+    @GET('/', GreetDTO)
+    public async greet(input: GreetDTO): Promise<{ message: string }> {
+        //@if i18n
+        return {message: this.i18n.t('greeting.hello', {name: input.name})}
+        //@else
+        return {message: `Hello, ${input.name}!`}
+        //@end
+    }
+}

package/template/packages/app/src/controllers/HealthController.ts

@@ -0,0 +1,13 @@
+import {Controller} from 'lakutata/com/entrypoint'
+import {GET} from 'lakutata/decorator/ctrl'
+
+export class HealthController extends Controller {
+
+    /**
+     * GET /health: the process answers
+     */
+    @GET('/health')
+    public async health(): Promise<{ status: string }> {
+        return {status: 'ok'}
+    }
+}

package/template/packages/app/src/dtos/GreetDTO.ts

@@ -0,0 +1,7 @@
+import {DTO} from 'lakutata'
+import {Expect} from 'lakutata/decorator/dto'
+
+export class GreetDTO extends DTO {
+    @Expect(DTO.String().optional().default('world').description('Who is greeted'))
+    public name: string
+}

package/template/packages/app/src/middlewares/Authenticate.ts

@@ -0,0 +1,22 @@
+import {Exception} from 'lakutata'
+import type {ActionInvocation, HTTPContext, Next} from 'lakutata/com/entrypoint'
+
+export class UnauthorizedException extends Exception {
+    public errno: string = 'E_UNAUTHORIZED'
+
+    public readonly statusCode: number = 401
+}
+
+/**
+ * The requests carry "Authorization: Bearer <API_TOKEN>" when the environment has an API_TOKEN (the health check excepted).
+ * Replace it with the authentication of the service (a session, a JWT verified with the keys of the identity provider…)
+ * @param invocation
+ * @param next
+ */
+export async function authenticate(invocation: ActionInvocation, next: Next): Promise<unknown> {
+    const token: string | undefined = process.env.API_TOKEN
+    const context: HTTPContext = invocation.context as HTTPContext
+    if (!token || context.route === '/health') return next()
+    if (context.request.headers.authorization !== `Bearer ${token}`) throw new UnauthorizedException('The request is not authenticated')
+    return next()
+}

package/template/packages/app/src/tests/App.spec.ts

@@ -0,0 +1,46 @@
+import {after, before, describe, it} from 'node:test'
+import assert from 'node:assert'
+import {Application} from 'lakutata'
+import {installerConfig} from '../config/Config.js'
+
+const PORT: number = Number(process.env.TEST_PORT ?? 18081)
+
+describe('{$APP_NAME}', (): void => {
+
+    let app: Application
+
+    before(async (): Promise<void> => {
+        process.env.API_TOKEN = 'test-token'
+        app = await new Promise<Application>((resolve: (app: Application) => void): void => {
+            Application.run(installerConfig(PORT)).onLaunched((launched: Application): void => resolve(launched))
+        })
+    })
+
+    after(async (): Promise<void> => {
+        await app?.dispose()
+    })
+
+    it('answers the health check without authentication', async (): Promise<void> => {
+        assert.deepStrictEqual(await (await fetch(`http://127.0.0.1:${PORT}/health`)).json(), {errno: null, errMsg: null, data: {status: 'ok'}})
+    })
+
+    it('greets the authenticated requests', async (): Promise<void> => {
+        const response: Response = await fetch(`http://127.0.0.1:${PORT}/example?name=you`, {headers: {Authorization: 'Bearer test-token'}})
+        assert.deepStrictEqual(await response.json(), {errno: null, errMsg: null, data: {message: 'Hello, you!'}})
+    })
+    //@if i18n
+
+    it('greets in the language of the request, its validation errors too', async (): Promise<void> => {
+        const headers: Record<string, string> = {'Authorization': 'Bearer test-token', 'Accept-Language': 'zh-CN,zh;q=0.9'}
+        assert.deepStrictEqual(await (await fetch(`http://127.0.0.1:${PORT}/example?name=you`, {headers: headers})).json(), {errno: null, errMsg: null, data: {message: '你好，you！'}})
+        const invalid = await (await fetch(`http://127.0.0.1:${PORT}/example?name=`, {headers: headers})).json() as { errMsg: string }
+        assert.strictEqual(invalid.errMsg, '"name" 不能为空')
+    })
+    //@end
+
+    it('refuses the requests without authentication', async (): Promise<void> => {
+        const response: Response = await fetch(`http://127.0.0.1:${PORT}/example`)
+        assert.strictEqual(response.status, 200)
+        assert.deepStrictEqual(await response.json(), {errno: 'E_UNAUTHORIZED', errMsg: 'The request is not authenticated', data: null})
+    })
+})

package/template/packages/app/tsconfig.json

@@ -0,0 +1,9 @@
+{
+  "extends": "lakutata/tsconfig.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "build",
+    "sourceMap": true
+  },
+  "include": ["src"]
+}