Updated libraries, docker engine version, docker distro version

This also officially publishes the changes from @eels.
Sorry it took so long.

.envdev

@@ -2,7 +2,7 @@ WEB_PORT=3100
 
 WEB_ORIGIN=http://localhost:3001
 
-DB_HOSTNAME=database
+DB_HOSTNAME=localhost
 DB_DATABASE=news
 DB_USERNAME=news
 DB_PASSWORD=venusaur
@@ -17,4 +17,4 @@ DB_LOGGING=
 SECRET_ACCESS=access
 
 # Select the default number of articles returned by a GET request
-QUERY_LIMIT=10
+PAGE_SIZE=10

Dockerfile

@@ -1,7 +1,7 @@
 
-FROM node:18-bullseye-slim
+FROM node:21-bookworm-slim
 WORKDIR "/app"
-COPY package*.json ./
+COPY package*.json /app
 RUN npm install --production
 COPY . /app
 EXPOSE 3100

README.md

@@ -22,112 +22,248 @@ Content-Type: application/json
 
 # API
 
+### `GET /news/:id?`
+
+Get either an array of articles (newest first), or a specified article if the optional "id" parameter is given.
+
+#### Response Body
+
+```jsonc
+[{
+	// [Number] index of the article
+	"index": index,
+
+	// [String] author of the article
+	"author": author,
+
+	// [String] raw body of the article
+	"body": body,
+
+	// [Number] number of times this article has been edited
+	"edits": edits,
+
+	// [String] body of the article rendered as HTML
+	"rendered": rendered,
+
+	// [String] title of the article
+	"title": title,
+
+	// [Date] time article was created
+	"createdAt": createdAt,
+
+	// [Date] time article was updated
+	"updatedAt": updatedAt,
+}]
 ```
-//NOTE: GET will return an empty array if a specific article can't be found
-//NOTE: you can add a "limit" query parameter to change the default limit
-GET /news?limit=10
 
+#### Available Query Parameters
 
-###
+- `fields`
+	- TYPE: `string`
+		A comma separated list of the field names you want returning, (index will always be returned)
+- `page`
+	- TYPE: `number`
+		The current page you want returning
+- `page_size`
+	- TYPE: `number`
+		The number of results to return. This superseeds the `PAGE_SIZE` environment variable for the query
 
+> **NOTE**
+> If a specific article is requested, then just that article is returned rather than an array
 
-//DOCS: get latest news, up to a default limit, or specify the index "id"
-GET /news/:id
+### `GET /news/archive/:id?`
 
+Get either an array of articles (oldest first), or a specified article if the optional "id" parameter is given.
 
-###
+#### Response Body
 
+```jsonc
+[{
+	// [Number] index of the article
+	"index": index,
 
-//DOCS: get the news starting from the beginning, up to a default limit, or specify the index "id"
-GET /news/archive/:id
+	// [String] author of the article
+	"author": author,
 
-//DOCS: result (if only a single article is specified, returns just that article rather than an array):
-[
-	{
-		"index": index,			//absolute index of the result
-		"title": title,			//title of the article
-		"author": author,		//author of the aricle
-		"body": body,			//body of the article
-		"rendered": rendered	//body rendered as HTML
-		"edits": edits			//number of times this article has been edited
-		"createdAt": createdAt	//time created
-		"updatedAt": updatedAt	//time updated
-	},
-	...
-]
+	// [String] raw body of the article
+	"body": body,
 
+	// [Number] number of times this article has been edited
+	"edits": edits,
 
-###
+	// [String] body of the article rendered as HTML
+	"rendered": rendered,
 
+	// [String] title of the article
+	"title": title,
 
-//DOCS: get the latest metadata, up to a default limit, or specify the index "id"
-GET /news/metadata/:id
+	// [Date] time article was created
+	"createdAt": createdAt,
 
-
-###
-
-
-//DOCS: get the metadata starting from the beginning, up to a default limit, or specify the index "id"
-GET /news/archive/metadata/:id
-
-//DOCS: result (if only a single article is specified, returns just that article rather than an array):
-[
-	{
-		"index": index,			//absolute index of the result
-		"title": title,			//title of the article
-		"author": author		//author of the article
-		"edits": edits			//number of times this article has been edited
-		"createdAt": createdAt	//time created
-		"updatedAt": updatedAt	//time updated
-	},
-	...
-]
-
-
-###
-
-
-//DOCS: send a formatted JSON object, returns new index on success, or error on failure
-POST /news
-Authorization: Bearer XXX
-
-{
-	"title": title		//title of the article
-	"author": author	//author of the article
-	"body": body		//body of the article
-}
-
-//DOCS: result (status 200 on success, otherwise an error status):
-{
-	"index": index		//new index of the article
-}
-
-
-###
-
-
-//DOCS: similar to `POST /news`, but allows overwriting an existing article
-PATCH /news/:id
-Authorization: Bearer XXX
-
-{
-	"title": title		//title of the article, optional
-	"author": author	//author of the article, optional
-	"body": body		//body of the article, optional
-}
-
-//DOCS: result: status 200 on success, otherwise an error status
-
-
-###
-
-
-//DOCS: remove an article from the news feed
-DELETE /news/:id
-Authorization: Bearer XXX
-
-//DOCS: result: status 200 on success, otherwise an error status
-
-
-###
+	// [Date] time article was updated
+	"updatedAt": updatedAt,
+}]
 ```
+
+#### Available Query Parameters
+
+- `fields`
+	- TYPE: `string`
+		A comma separated list of the field names you want returning, (index will always be returned)
+- `page`
+	- TYPE: `number`
+		The current page you want returning
+- `page_size`
+	- TYPE: `number`
+		The number of results to return. This superseeds the `PAGE_SIZE` environment variable for the query
+
+> **NOTE**
+> If a specific article is requested, then just that article is returned rather than an array
+
+### `GET /news/metadata/:id?`
+
+Get either an array of metadata (newest first), or a specified article's metadata if the optional "id" parameter is given.
+
+#### Response Body
+
+```jsonc
+[{
+	// [Number] index of the article
+	"index": index,
+
+	// [String] author of the article
+	"author": author,
+
+	// [Number] number of times this article has been edited
+	"edits": edits,
+
+	// [String] title of the article
+	"title": title,
+
+	// [Date] time article was created
+	"createdAt": createdAt,
+
+	// [Date] time article was updated
+	"updatedAt": updatedAt,
+}]
+```
+
+#### Available Query Parameters
+
+- `fields`
+	- TYPE: `string`
+		A comma separated list of the field names you want returning, (index will always be returned)
+- `page`
+	- TYPE: `number`
+		The current page you want returning
+- `page_size`
+	- TYPE: `number`
+		The number of results to return. This superseeds the `PAGE_SIZE` environment variable for the query
+
+> **NOTE**
+> If a specific article is requested, then just that article is returned rather than an array
+
+### `GET /news/archive/metadata/:id?`
+
+Get either an array of metadata (oldest first), or a specified article's metadata if the optional "id" parameter is given.
+
+#### Response Body
+
+```jsonc
+[{
+	// [Number] index of the article
+	"index": index,
+
+	// [String] author of the article
+	"author": author,
+
+	// [Number] number of times this article has been edited
+	"edits": edits,
+
+	// [String] title of the article
+	"title": title,
+
+	// [Date] time article was created
+	"createdAt": createdAt,
+
+	// [Date] time article was updated
+	"updatedAt": updatedAt,
+}]
+```
+
+#### Available Query Parameters
+
+- `fields`
+	- TYPE: `string`
+		A comma separated list of the field names you want returning, (index will always be returned)
+- `page`
+	- TYPE: `number`
+		The current page you want returning
+- `page_size`
+	- TYPE: `number`
+		The number of results to return. This supersedes the `PAGE_SIZE` environment variable for the query
+
+> **NOTE**
+> If a specific article is requested, then just that article is returned rather than an array
+
+---
+
+### `POST /news`
+
+> **IMPORTANT**
+> Requires valid JWT Authorization header (Authorization: Bearer XXX)
+
+Create a new article resource, returns either the new article's index on success, or an error on failure.
+
+#### Request Body
+
+```jsonc
+{
+	// [String] OPTIONAL: title of the article
+	"title": title,
+
+	// [String] OPTIONAL: author of the article
+	"author": author,
+
+	// [String] OPTIONAL: body of the article
+	"body": body,
+}
+```
+
+#### Response Body
+
+```jsonc
+{
+	// [Number]: new index of the article
+	"index": index,
+}
+```
+
+### `PATCH /news/:id`
+
+> **IMPORTANT**
+> Requires valid JWT Authorization header (Authorization: Bearer XXX)
+
+Update an existing article resource, returns either status code 200 on success, or an error status on failure.
+
+#### Request Body
+
+```jsonc
+{
+	// [String] OPTIONAL: title of the article
+	"title": title,
+
+	// [String] OPTIONAL: author of the article
+	"author": author,
+
+	// [String] OPTIONAL: body of the article
+	"body": body,
+}
+```
+
+### `DELETE /news/:id`
+
+> **IMPORTANT**
+> Requires valid JWT Authorization header (Authorization: Bearer XXX)
+
+Remove an existing article resource from the news feed, returns either status code 200 on success, or an error status on failure.

configure-script.js

@@ -43,8 +43,7 @@ const question = (prompt, def = null) => {
 
 	//generate the files
 	const ymlfile = `
-version: '3'
-
+version: '3.8'
 services:
   ${appName}:
     build:
@@ -66,7 +65,7 @@ services:
       - DB_USERNAME=${appDBUser}
       - DB_PASSWORD=${appDBPass}
       - DB_TIMEZONE=Australia/Sydney
-      - QUERY_LIMIT=10
+      - PAGE_SIZE=10
       - SECRET_ACCESS=${appSecretAccess}
     networks:
       - app-network
@@ -85,9 +84,7 @@ services:
       - ./mysql:/var/lib/mysql
       - ./startup.sql:/docker-entrypoint-initdb.d/startup.sql:ro
   traefik_${appName}:
-    container_name: ${appName}_traefik
-    image: "traefik:v2.4"
-    container_name: "traefik"
+    image: "traefik:v2.10"
     command:
       - "--log.level=ERROR"
       - "--api.insecure=false"
@@ -111,9 +108,9 @@ networks:
 `;
 
 	const dockerfile = `
-FROM node:18-bullseye-slim
+FROM node:21-bookworm-slim
 WORKDIR "/app"
-COPY package*.json ./
+COPY package*.json /app
 RUN npm install --production
 COPY . /app
 EXPOSE ${appPort}

package.json

@@ -1,6 +1,6 @@
 {
   "name": "news-server",
-  "version": "1.6.4",
+  "version": "1.7.0",
   "description": "An API centric news server. Uses Sequelize and mariaDB by default.",
   "main": "server/server.js",
   "scripts": {
@@ -22,15 +22,12 @@
     "cors": "^2.8.5",
     "dotenv": "^16.3.1",
     "express": "^4.18.2",
-    "jsonwebtoken": "^9.0.0",
-    "mariadb": "^3.2.0",
-    "markdown-it": "^13.0.1",
-    "sequelize": "^6.32.1"
+    "jsonwebtoken": "^9.0.2",
+    "mariadb": "^3.2.3",
+    "markdown-it": "^13.0.2",
+    "sequelize": "^6.35.2"
   },
   "devDependencies": {
-    "nodemon": "^2.0.22"
-  },
-  "overrides": {
-    "semver": "^7.5.2"
+    "nodemon": "^3.0.2"
   }
 }

server/news/index.js

@@ -12,14 +12,10 @@ const edit = require('./edit');
 const remove = require('./remove');
 
 //basic route management (all query possibilities)
-router.get('/', cors(), query(false, false));
-router.get('/:id(\\d+)', cors(), query(false, false));
-router.get('/archive', cors(), query(true, false));
-router.get('/archive/:id(\\d+)', cors(), query(true, false));
-router.get('/metadata', cors(), query(false, true));
-router.get('/metadata/:id(\\d+)', cors(), query(false, true));
-router.get('/archive/metadata', cors(), query(true, true));
-router.get('/archive/metadata/:id(\\d+)', cors(), query(true, true));
+router.get('/:id(\\d+)?', cors(), query(false, false));
+router.get('/archive/:id(\\d+)?', cors(), query(true, false));
+router.get('/metadata/:id(\\d+)?', cors(), query(false, true));
+router.get('/archive/metadata/:id(\\d+)?', cors(), query(true, true));
 
 //use middleware to authenticate the rest of the routes
 router.use(cors({

server/news/query.js

@@ -1,18 +1,45 @@
-const { Op } = require('sequelize');
 const { articles } = require('../database/models');
 
 //the query function that can be reused
 const query = (ascending, metadataOnly) => async (req, res) => {
+	if (process.env.QUERY_LIMIT) {
+		process.env.PAGE_SIZE = process.env.QUERY_LIMIT;
+		console.warn('The use of QUERY_LIMIT is deprecated. Please use PAGE_SIZE instead.');
+	}
+
+	if (req.query.limit) {
+		req.query.page_size = req.query.limit;
+		console.warn('The use of the limit parameter is deprecated. Please use page_size instead.');
+	}
+
+	const PAGE_SIZE = parseInt(req.query.page_size) || parseInt(process.env.PAGE_SIZE) || 999;
+	const PAGE = parseInt(req.query.page) || 1;
+	const ARTICLE_ID = req.params.id ? parseInt(req.params.id) : undefined;
+	const FIELDS = req.query.fields ? req.query.fields.split(',') : undefined;
+
+	const attributes = [
+		'index',
+		'author',
+		'createdAt',
+		'edits',
+		'title',
+		'updatedAt',
+	].concat(metadataOnly ? [] : [
+		'body',
+		'rendered'
+	]);
+
+	//filter out attributes that aren't requested
+	const attributesToFetch = FIELDS ? attributes.filter((attr) => {
+		return FIELDS.includes(attr) || attr === 'index';
+	}) : attributes;
+
 	//specific search (id is defined)
-	if (req.params.id && typeof(parseInt(req.params.id)) === 'number') {
+	if (typeof(ARTICLE_ID) === 'number' && !isNaN(ARTICLE_ID)) {
 		const result = await articles.findOne({
-			attributes: [
-				'index', 'title', 'author', 'edits', 'createdAt', 'updatedAt', ...(!metadataOnly ? ['body', 'rendered'] : [])
-			],
+			attributes: attributesToFetch,
 			where: {
-				index: {
-					[Op.eq]: ascending ? parseInt(req.params.id) : (await articles.max('index')) - parseInt(req.params.id) + 1
-				}
+				index: ascending ? ARTICLE_ID : (await articles.max('index') - ARTICLE_ID) + 1,
 			}
 		});
 
@@ -23,16 +50,16 @@ const query = (ascending, metadataOnly) => async (req, res) => {
 	//default search
 	else {
 		const result = await articles.findAndCountAll({
-			attributes: [
-				'index', 'title', 'author', 'edits', 'createdAt', 'updatedAt', ...(!metadataOnly ? ['body', 'rendered'] : [])
-			],
+			attributes: attributesToFetch,
+			limit: PAGE_SIZE,
+			offset: Math.max((PAGE - 1) * PAGE_SIZE, 0),
 			order: [
 				['index', ascending ? 'ASC' : 'DESC']
-			],
-			limit: parseInt(req.query.limit) || parseInt(process.env.QUERY_LIMIT) || 999
+			]
 		});
 
-		return res.status(200).json(result.rows || result);
+		//result is empty array if failed to find
+		return res.status(200).json(result.rows || result || []);
 	}
 };
 

server/server.js

@@ -24,48 +24,4 @@ app.get('*', (req, res) => {
 server.listen(process.env.WEB_PORT || 3100, async (err) => {
 	await database.sync();
 	console.log(`listening to localhost:${process.env.WEB_PORT || 3100}`);
-
-	//COMPATABILITY: parse the unrendered data from the database
-	const markdownIt = require('markdown-it')();
-	const { articles, revisions } = require('./database/models');
-
-	const missingArticles = await articles.findAll({
-		where: {
-			rendered: ''
-		}
-	});
-
-	const missingRevisions = await revisions.findAll({
-		where: {
-			rendered: ''
-		}
-	});
-
-	await Promise.all(
-		missingArticles.map(async ma => {
-			ma.update({
-				rendered: markdownIt.render(ma.body)
-			}, {
-				where: {
-					index: ma.index
-				}
-			});
-		})
-	)
-		.then(result => {if (result.length > 0) console.log('Rendered articles in HTML'); })
-	;
-
-	await Promise.all(
-		missingRevisions.map(async mr => {
-			mr.update({
-				rendered: markdownIt.render(mr.body)
-			}, {
-				where: {
-					index: mr.index
-				}
-			});
-		})
-	)
-	.then(result => {if (result.length > 0) console.log('Rendered revisions in HTML'); })
-	;
 });

tools/migrations/version-1.3.0.sql

@@ -1,6 +0,0 @@
-use news;
-ALTER TABLE revisions CHANGE COLUMN id `index` INTEGER(11) UNIQUE NOT NULL AUTO_INCREMENT;
-
-ALTER TABLE revisions DROP FOREIGN KEY revisions_ibfk_1;
-
-ALTER TABLE revisions CHANGE COLUMN originalIndex originalIndex INTEGER(11);

tools/migrations/version-1.4.0.sql

@@ -1,4 +0,0 @@
-ALTER TABLE articles ADD COLUMN rendered TEXT DEFAULT "" AFTER body;
-
-ALTER TABLE revisions ADD COLUMN rendered TEXT DEFAULT "" AFTER body;
-