beavuck-time 2.1.21

package/README.md

@@ -0,0 +1,215 @@
+# ⏲️ Beavuck Time
+
+## 📊 Status
+
+[![Quality gate](https://sonarcloud.io/api/project_badges/quality_gate?project=beavuck-services_time)](https://sonarcloud.io/summary/new_code?id=beavuck-services_time)
+
+[![Security Rating](https://sonarcloud.io/api/project_badges/measure?project=beavuck-services_time&metric=security_rating)](https://sonarcloud.io/summary/new_code?id=beavuck-services_time)
+[![Vulnerabilities](https://sonarcloud.io/api/project_badges/measure?project=beavuck-services_time&metric=vulnerabilities)](https://sonarcloud.io/summary/new_code?id=beavuck-services_time)
+
+[![Reliability Rating](https://sonarcloud.io/api/project_badges/measure?project=beavuck-services_time&metric=reliability_rating)](https://sonarcloud.io/summary/new_code?id=beavuck-services_time)
+[![Bugs](https://sonarcloud.io/api/project_badges/measure?project=beavuck-services_time&metric=bugs)](https://sonarcloud.io/summary/new_code?id=beavuck-services_time)
+
+[![Code Smells](https://sonarcloud.io/api/project_badges/measure?project=beavuck-services_time&metric=code_smells)](https://sonarcloud.io/summary/new_code?id=beavuck-services_time)
+[![Maintainability Rating](https://sonarcloud.io/api/project_badges/measure?project=beavuck-services_time&metric=sqale_rating)](https://sonarcloud.io/summary/new_code?id=beavuck-services_time)
+[![Technical Debt](https://sonarcloud.io/api/project_badges/measure?project=beavuck-services_time&metric=sqale_index)](https://sonarcloud.io/summary/new_code?id=beavuck-services_time)
+
+[![Lines of Code](https://sonarcloud.io/api/project_badges/measure?project=beavuck-services_time&metric=ncloc)](https://sonarcloud.io/summary/new_code?id=beavuck-services_time)
+[![Duplicated Lines (%)](https://sonarcloud.io/api/project_badges/measure?project=beavuck-services_time&metric=duplicated_lines_density)](https://sonarcloud.io/summary/new_code?id=beavuck-services_time)
+
+[![Coverage](https://sonarcloud.io/api/project_badges/measure?project=beavuck-services_time&metric=coverage)](https://sonarcloud.io/summary/new_code?id=beavuck-services_time)
+
+---
+
+## 💡 Why
+
+You can't count on client devices to all be set up with the correct date and time.
+
+But keeping track of time is usually busywork, not the business of your core APIs. And you probably don't want to flood
+your own APIs, whenever you want to get an accurate timestamp for entities in your apps.
+
+So you can set up this simple microservice, whose only job should be to answer the question: "what time is it right
+now?"
+
+---
+
+## 🎯 What
+
+Get the current time in ISO format, in UTC timezone.
+
+This lightweight service focuses on one job.
+
+It needs no persistence layer, is capable of handling multiple concurrent requests, and is protected by a simple
+CORS config for security and performance reasons.
+
+Dockerized for easy deployment and scaling.
+
+---
+
+## 🔍 Where
+
+The code lives on [GitLab](https://gitlab.com/beavuck-services/time),
+and the Docker image is hosted on [Docker Hub](https://hub.docker.com/r/beavuck/time)
+
+### 🦊 GitLab
+
+You can find the code on GitLab, where, once you have read the [CONTRIBUTING.md](CONTRIBUTING.md) file, you can also
+create issues and merge requests.
+
+Feel free to fork the repo and make your own changes at will, as per the [UNLICENSE](UNLICENSE).
+
+### 🐳 Docker Hub
+
+Most devs will only use Docker Hub for their purposes with this project, to use it as is as a dependency for their own
+projects. On Docker Hub, while you're developing, you should use the `beavuck/time:latest` tag to always get the latest
+version.
+
+When the time comes to go to production, to protect yourself from surprise breaking changes, you should instead point to
+specific minor version tags, such as `beavuck/time:2.0` : those will not get breaking changes, but they will get
+security updates and bug fixes while they're active.
+
+---
+
+## ⚙️ Usage
+
+### 🪧 Set up (docker-compose example)
+
+To run the service in a docker-compose environment, add this in your `docker-compose.yml`'s services section:
+
+```yaml
+time:
+    image: beavuck/time:latest
+    ports:
+        - 'SOME_PORT_NUMBER:3000'
+        # HOST_PORT:CONTAINER_PORT (Since we are in a container, CONTAINER_PORT corresponds to the API_PORT variable below)
+    environment:
+        - HOST_URL: https://time-api.example.com
+        # HOST_URL: That API's URL. Essential for CORS config.
+        - TRUSTED_ORIGINS: https://my.app.com,https://my-other.app.com
+        # TRUSTED_ORIGINS: To allow requests from any origin, include * (not recommended). If empty, will only allow requests from the HOST_URL's origin. Defaults to the HOST_URL's origin
+        - API_PORT: 3000
+        # API_PORT: Optional. Internal port when in a container. Defaults to 3000
+        - RATE_LIMIT: 100
+        # RATE_LIMIT: Optional. Max allowed number of requests per minute for each IP address. If negative or 0, no limit. Defaults to no limit
+        - LOG_LEVEL: info
+        # LOG_LEVEL: Optional. Logging levels include error, warn, info, http, verbose, debug, silly. Defaults to info
+        - MAX_LOG_FILES: 64
+        # MAX_LOG_FILES: Optional. Maximum number of logs to keep. This can be a number of files or number of days. If using days, add 'd' as the suffix. Default is 64
+        - MAX_SIZE_LOG_FILES: 1m
+        # MAX_SIZE_LOG_FILES: Optional. Maximum size of the file after which it will rotate. This can be a number of bytes, or units of kb, mb, and gb. If using the units, add 'k', 'm', or 'g' as the suffix. The units need to directly follow the number. Default is 1m
+```
+
+Here's the simple docker compose file I used to test this service locally:
+
+```yaml
+services:
+    time:
+        image: beavuck/time:latest
+        ports:
+            - '3000:3000'
+        environment:
+            HOST_URL: http://127.0.0.1:3000
+            TRUSTED_ORIGINS: http://127.0.0.1:8000,http://localhost:8000
+            LOG_LEVEL: debug
+```
+
+When you're ready, just run your services with:
+
+```shell
+docker compose up -d
+```
+
+### ✨ Using the service
+
+Now, when you run:
+
+```shell
+curl --location 'http://localhost:{{SOME_PORT_NUMBER}}/now' \
+--header 'Origin: {{SOME_TRUSTED_ORIGIN}}'
+```
+
+you should expect an answer such as:
+
+```json
+{
+    "now": "2024-06-15T12:35:48.022Z"
+}
+```
+
+---
+
+## 🛡️ CORS
+
+This service is protected by a CORS policy, which you can configure by setting the `TRUSTED_ORIGINS` environment
+variable.
+
+When you use the API, keep in mind what roles these headers play:
+
+| `"Origin:"`                                  | `"Referrer:"`*                 | Result |
+| -------------------------------------------- | ------------------------------ | ------ |
+| Defined and API `TRUSTED_ORIGINS` set to `*` | Whatever                       | ✅     |
+| Trusted                                      | Whatever                       | ✅     |
+| Same as this API's host                      | Whatever                       | ✅     |
+| Not defined                                  | Same as this API's host        | ✅     |
+| Defined and not trusted                      | Whatever                       | 🛑     |
+| Not defined                                  | Not defined                    | 🛑     |
+| Not defined or not trusted                   | Different from this API's host | 🛑     |
+
+*AKA `Referer` (sic).
+
+---
+
+## 📚 Use cases
+
+### Batch `POST`s
+
+Suppose you're creating timestamped entities in your app, and you want to send them in a batch to your API. Your API
+knows the current time when it gets the request, but not the creation time of each entity.
+
+```mermaid
+sequenceDiagram
+    participant 📱 Client
+    participant 🖥 Core API
+    📱 Client->>🖥 Core API: POST /entities [{...}, {...}, {...}]
+```
+
+And querying your core API for the current time for each entity is a waste of resources -- that's why you're batching
+the operation in the first place.
+
+```mermaid
+sequenceDiagram
+    participant 📱 Client
+    participant 🖥 Core API
+    📱 Client->>🖥 Core API: GET /now
+    🖥 Core API->>📱 Client: {"now": "2024-06-15T12:35:48.022Z"}
+    📱 Client->>🖥 Core API: GET /now
+    🖥 Core API->>📱 Client: {"now": "2024-06-15T12:35:49.071Z"}
+    📱 Client->>🖥 Core API: GET /now
+    🖥 Core API->>📱 Client: {"now": "2024-06-15T12:35:49.243Z"}
+    📱 Client->>🖥 Core API: POST /entities [{...}, {...}, {...}]
+```
+
+So you can use this service to get the current time whenever you need it, and use that as the creation time for each
+entity.
+
+```mermaid
+sequenceDiagram
+    participant 📱 Client
+    participant 🕒 Time
+    participant 🖥 Core API
+    📱 Client->>🕒 Time: GET /now
+    🕒 Time->>📱 Client: {"now": "2024-06-15T12:35:48.022Z"}
+    📱 Client->>🕒 Time: GET /now
+    🕒 Time->>📱 Client: {"now": "2024-06-15T12:35:49.071Z"}
+    📱 Client->>🕒 Time: GET /now
+    🕒 Time->>📱 Client: {"now": "2024-06-15T12:35:49.243Z"}
+    📱 Client->>🖥 Core API: POST /entities [{...}, {...}, {...}]
+```
+
+---
+
+## 📜 License
+
+Have at it.
+
+This project uses the Unlicense. See the [UNLICENSE](UNLICENSE) file for details.

package/UNLICENSE

@@ -0,0 +1,24 @@
+This is free and unencumbered software released into the public domain.
+
+Anyone is free to copy, modify, publish, use, compile, sell, or
+distribute this software, either in source code form or as a compiled
+binary, for any purpose, commercial or non-commercial, and by any
+means.
+
+In jurisdictions that recognize copyright laws, the author or authors
+of this software dedicate any and all copyright interest in the
+software to the public domain. We make this dedication for the benefit
+of the public at large and to the detriment of our heirs and
+successors. We intend this dedication to be an overt act of
+relinquishment in perpetuity of all present and future rights to this
+software under copyright law.
+
+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 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.
+
+For more information, please refer to <https://unlicense.org>

package/api-tests/bruno/bruno.json

@@ -0,0 +1,9 @@
+{
+  "version": "1",
+  "name": "Time",
+  "type": "collection",
+  "ignore": [
+    "node_modules",
+    ".git"
+  ]
+}

package/api-tests/bruno/collection.bru

@@ -0,0 +1,7 @@
+meta {
+  name: Time
+}
+
+auth {
+  mode: none
+}

package/api-tests/bruno/environments/local.bru

@@ -0,0 +1,8 @@
+vars {
+  BASE_URL: http://localhost:3000
+  TRUSTED_ORIGIN: http://localhost:8477
+  NON_TRUSTED_ORIGIN: http://localhost:9632
+  NON_RECOGNIZED_REFERRER: http://localhost:9236
+  RFC_3339_REGEX: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}.\d{3}Z$
+  CORS_REGEX: [cC][oO][rR][sS]
+}

package/api-tests/bruno/now/nok/nok_no_origin.bru

@@ -0,0 +1,19 @@
+meta {
+  name: nok_no_origin
+  type: http
+  seq: 2
+}
+
+get {
+  url: {{BASE_URL}}/now
+  body: none
+  auth: inherit
+}
+
+assert {
+  res.status: eq 403
+  res.body: isDefined
+  res.body.message: isDefined
+  res.body.message: matches {{CORS_REGEX}}
+  res.responseTime: lt 200
+}

package/api-tests/bruno/now/nok/nok_non_recognized_referrer.bru

@@ -0,0 +1,23 @@
+meta {
+  name: nok_non_recognized_referrer
+  type: http
+  seq: 4
+}
+
+get {
+  url: {{BASE_URL}}/now
+  body: none
+  auth: inherit
+}
+
+headers {
+  Referrer: {{NON_RECOGNIZED_REFERRER}}
+}
+
+assert {
+  res.status: eq 403
+  res.body: isDefined
+  res.body.message: isDefined
+  res.body.message: matches {{CORS_REGEX}}
+  res.responseTime: lt 200
+}

package/api-tests/bruno/now/nok/nok_non_trusted_origin.bru

@@ -0,0 +1,23 @@
+meta {
+  name: nok_non_trusted_origin
+  type: http
+  seq: 1
+}
+
+get {
+  url: {{BASE_URL}}/now
+  body: none
+  auth: inherit
+}
+
+headers {
+  Origin: {{NON_TRUSTED_ORIGIN}}
+}
+
+assert {
+  res.status: eq 403
+  res.body: isDefined
+  res.body.message: isDefined
+  res.body.message: matches {{CORS_REGEX}}
+  res.responseTime: lt 200
+}

package/api-tests/bruno/now/nok/nok_non_truted_origin_nor_referrer.bru

@@ -0,0 +1,24 @@
+meta {
+  name: nok_non_truted_origin_nor_referrer
+  type: http
+  seq: 3
+}
+
+get {
+  url: {{BASE_URL}}/now
+  body: none
+  auth: inherit
+}
+
+headers {
+  Origin: {{NON_TRUSTED_ORIGIN}}
+  Referrer: {{NON_RECOGNIZED_REFERRER}}
+}
+
+assert {
+  res.status: eq 403
+  res.body: isDefined
+  res.body.message: isDefined
+  res.body.message: matches {{CORS_REGEX}}
+  res.responseTime: lt 200
+}

package/api-tests/bruno/now/ok/ok_same_origin.bru

@@ -0,0 +1,23 @@
+meta {
+  name: ok_same_origin
+  type: http
+  seq: 2
+}
+
+get {
+  url: {{BASE_URL}}/now
+  body: none
+  auth: inherit
+}
+
+headers {
+  Origin: {{BASE_URL}}
+}
+
+assert {
+  res.status: eq 200
+  res.body: isDefined
+  res.body.now: isDefined
+  res.body.now: matches {{RFC_3339_REGEX}}
+  res.responseTime: lt 200
+}

package/api-tests/bruno/now/ok/ok_same_referrer.bru

@@ -0,0 +1,23 @@
+meta {
+  name: ok_same_referrer
+  type: http
+  seq: 3
+}
+
+get {
+  url: {{BASE_URL}}/now
+  body: none
+  auth: inherit
+}
+
+headers {
+  Referrer: {{BASE_URL}}
+}
+
+assert {
+  res.status: eq 200
+  res.body: isDefined
+  res.body.now: isDefined
+  res.body.now: matches {{RFC_3339_REGEX}}
+  res.responseTime: lt 200
+}

package/api-tests/bruno/now/ok/ok_trusted_origin.bru

@@ -0,0 +1,23 @@
+meta {
+  name: ok_trusted_origin
+  type: http
+  seq: 1
+}
+
+get {
+  url: {{BASE_URL}}/now
+  body: none
+  auth: inherit
+}
+
+headers {
+  Origin: {{TRUSTED_ORIGIN}}
+}
+
+assert {
+  res.status: eq 200
+  res.body: isDefined
+  res.body.now: isDefined
+  res.body.now: matches {{RFC_3339_REGEX}}
+  res.responseTime: lt 200
+}

package/build/api.js

@@ -0,0 +1,20 @@
+"use strict";
+// src/api.ts
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.api = void 0;
+const express_1 = __importDefault(require("express"));
+const corsMiddleware_1 = require("./middlewares/corsMiddleware");
+const errorHandler_1 = require("./middlewares/errorHandler");
+const rateLimiter_1 = require("./middlewares/rateLimiter");
+const notFoundHandler_1 = require("./middlewares/notFoundHandler");
+const routes_1 = require("./routes/routes");
+exports.api = (0, express_1.default)();
+exports.api.disable('x-powered-by');
+exports.api.use(corsMiddleware_1.corsMiddleware);
+exports.api.use(errorHandler_1.errorHandler);
+exports.api.use(rateLimiter_1.rateLimiter);
+(0, routes_1.RegisterRoutes)(exports.api);
+exports.api.use(notFoundHandler_1.notFoundHandler);

package/eslint.config.mjs

@@ -0,0 +1,28 @@
+// eslint.config.mjs
+
+import globals from 'globals'
+import pluginJs from '@eslint/js'
+import tseslint from 'typescript-eslint'
+
+/** @type {import('eslint').Linter.Config[]} */
+export default [
+    {files: ['**/*.{js,mjs,cjs,ts}']},
+    {languageOptions: {globals: globals.browser}},
+    pluginJs.configs.recommended,
+    ...tseslint.configs.recommended,
+    {
+        rules: {
+            '@typescript-eslint/no-explicit-any': 'off',
+            'no-restricted-syntax': [
+                'error', {
+                    selector: 'CallExpression[callee.object.name="console"]',
+                    message: 'Don\'t use console -- use the configured logger instead',
+                },
+                'error', {
+                    selector: ':not(BinaryExpression:matches([operator="!=="], [operator="==="])) > Literal[value="null"]',
+                    message: 'Usage of "null" is deprecated except when received from legacy APIs. Use "undefined" instead',
+                },
+            ],
+        },
+    },
+]

package/openapi/swagger.json

@@ -0,0 +1,75 @@
+{
+	"openapi": "3.0.0",
+	"components": {
+		"examples": {},
+		"headers": {},
+		"parameters": {},
+		"requestBodies": {},
+		"responses": {},
+		"schemas": {
+			"IsoTimestamp": {
+				"type": "string",
+				"format": "date-time",
+				"description": "Stringified date-time in RFC 3339 format (often referred to as ISO 8601 format)\nSee [RFC 3339 section 5.6](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6)"
+			},
+			"Now": {
+				"properties": {
+					"now": {
+						"$ref": "#/components/schemas/IsoTimestamp"
+					}
+				},
+				"required": [
+					"now"
+				],
+				"type": "object",
+				"additionalProperties": false,
+				"example": {
+					"now": "2019-08-24T14:15:22Z"
+				}
+			}
+		},
+		"securitySchemes": {}
+	},
+	"info": {
+		"title": "beavuck-time",
+		"version": "2.1.21",
+		"description": "Get time in ISO format, in UTC timezone, from a simple, lightweight node server",
+		"license": {
+			"name": "Unlicense"
+		},
+		"contact": {
+			"name": "Alexis Drai"
+		}
+	},
+	"paths": {
+		"/now": {
+			"get": {
+				"operationId": "getNow",
+				"responses": {
+					"200": {
+						"description": "Ok",
+						"content": {
+							"application/json": {
+								"schema": {
+									"$ref": "#/components/schemas/Now"
+								}
+							}
+						}
+					}
+				},
+				"description": "Get the current time in ISO format, in UTC timezone",
+				"summary": "Get current time",
+				"tags": [
+					"now"
+				],
+				"security": [],
+				"parameters": []
+			}
+		}
+	},
+	"servers": [
+		{
+			"url": "/"
+		}
+	]
+}

package/package.json

@@ -0,0 +1,79 @@
+{
+  "name": "beavuck-time",
+  "version": "2.1.21",
+  "description": "Get time in ISO format, in UTC timezone, from a simple, lightweight node server",
+  "keywords": [],
+  "homepage": "https://gitlab.com/beavuck-services/time",
+  "bugs": {
+    "url": "https://gitlab.com/beavuck-services/time/-/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://gitlab.com/beavuck-services/time.git"
+  },
+  "license": "Unlicense",
+  "author": "Alexis Drai",
+  "type": "commonjs",
+  "main": "build/api.js",
+  "scripts": {
+    "run-integration-tests": "cd api-tests/bruno && npm install -g @usebruno/cli && bru run --env local --bail",
+    "up-patch": "npm version patch --no-git-tag-version",
+    "up-minor": "npm version minor --no-git-tag-version",
+    "up-major": "npm version major --no-git-tag-version",
+    "update-dependencies": "ncu --format group && ncu -u && npm install --verbose && npm prune --verbose && npm audit fix --verbose",
+    "lint": "eslint --fix src/",
+    "format": "prettier --write src/ --log-level warn",
+    "clean": "npm run lint && npm run format",
+    "test": "DOTENV_CONFIG_PATH=./.env.test jest --coverage",
+    "build": "tsoa spec-and-routes && tsc",
+    "start": "node build/server.js",
+    "go": "npm install && npm run build && npm run clean && npm run test && npm start"
+  },
+  "dependencies": {
+    "@dotenvx/dotenvx": "^1.48.0",
+    "cors": "^2.8.5",
+    "express": "^5.1.0",
+    "express-rate-limit": "^8.0.1",
+    "http-status-codes": "^2.3.0",
+    "joi": "^17.13.3",
+    "tsoa": "^6.6.0",
+    "winston": "^3.17.0",
+    "winston-daily-rotate-file": "^5.0.0"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.31.0",
+    "@types/cors": "^2.8.19",
+    "@types/express": "^5.0.3",
+    "@types/jest": "^30.0.0",
+    "@types/node": "^24.0.15",
+    "@types/supertest": "^6.0.3",
+    "eslint": "^9.31.0",
+    "globals": "^16.3.0",
+    "jest": "^30.0.4",
+    "nodemon": "^3.1.10",
+    "npm-check-updates": "^18.0.1",
+    "prettier": "3.6.2",
+    "supertest": "^7.1.3",
+    "ts-jest": "^29.4.0",
+    "ts-node": "^10.9.2",
+    "typescript": "^5.8.3",
+    "typescript-eslint": "^8.37.0"
+  },
+  "engines": {
+    "node": ">=18.20.8"
+  },
+  "prettier": {
+    "experimentalTernaries": true,
+    "semi": false,
+    "printWidth": 96,
+    "tabWidth": 2,
+    "useTabs": false,
+    "singleQuote": true,
+    "jsxSingleQuote": false,
+    "bracketSameLine": false,
+    "arrowParens": "avoid",
+    "endOfLine": "lf",
+    "bracketSpacing": false,
+    "trailingComma": "all"
+  }
+}

package/sonar-project.properties

@@ -0,0 +1,9 @@
+sonar.projectKey=beavuck-services_time
+sonar.organization=beavuck-services
+sonar.sources=.
+sonar.exclusions=**/node_modules/**, **/coverage/**, **/build/**, **/build/**, **/api-tests/**, *package*.json, src/routes/routes.ts
+sonar.coverage.exclusions=src/__tests__/utils/urlUtil.test.ts, src/__tests__/middlewares/errorHandler.test.ts, src/__tests__/config/corsOptions.test.ts, src/__tests__/api.test.ts, src/config/logger.ts, src/server.ts, src/middlewares/rateLimiter.ts, src/routes/routes.ts
+sonar.sourceEncoding=UTF-8
+sonar.typescript.tsconfigPaths=tsconfig.json
+sonar.coverage.inclusions=src/**/*.*
+sonar.javascript.lcov.reportPaths=coverage/lcov.info