adapt-authoring-content 3.2.2 → 3.2.4

package/lib/ContentModule.js

@@ -2,7 +2,7 @@ import { AbstractApiModule } from 'adapt-authoring-api'
 import { Hook, stringifyValues } from 'adapt-authoring-core'
 import { createObjectId, parseObjectId } from 'adapt-authoring-mongodb'
 import { ObjectId } from 'mongodb'
-import { ContentTree, buildAssetUsagePipeline, computeSortOrderOps, contentTypeToSchemaName, extractAssetIds, formatFriendlyId, parseMaxSeq } from './utils.js'
+import { ContentTree, buildAssetUsagePipeline, computeSortOrderOps, contentTypeToSchemaName, extractAssetIds, fieldsToProjection, formatFriendlyId, parseMaxSeq, treeEtag } from './utils.js'
 /**
  * Module which handles course content
  * @memberof content
@@ -679,19 +679,39 @@ class ContentModule extends AbstractApiModule {
       if (!req.auth.isSuper && this.accessCheckHook.hasObservers && !(await this.accessCheckHook.invoke(req, course)).every(Boolean)) {
         throw this.app.errors.NOT_FOUND.setData({ type: 'content', id: _courseId })
       }
-      const lastModified = new Date(course.updatedAt)
-      lastModified.setMilliseconds(0) // HTTP dates are second-precision; must match before comparing
-      const ifModifiedSince = req.headers['if-modified-since'] && new Date(req.headers['if-modified-since'])
-      if (ifModifiedSince && lastModified <= ifModifiedSince) {
+      const treeFields = [
+        '_id',
+        '_parentId',
+        '_courseId',
+        '_type',
+        '_sortOrder',
+        'title',
+        'displayTitle',
+        '_friendlyId',
+        '_component',
+        '_layout',
+        '_menu',
+        '_theme',
+        '_enabledPlugins',
+        '_colorLabel',
+        'heroImage',
+        'updatedAt'
+      ]
+      // ETag (not Last-Modified): folds the projected field list into the
+      // validator so the cache busts when the response shape changes, not just
+      // when the course data does — otherwise an added field stays missing for
+      // unedited courses whose updatedAt never moves.
+      const etag = treeEtag(course.updatedAt, treeFields)
+      if (req.headers['if-none-match'] === etag) {
         return res.status(304).end()
       }
       const items = await this.find(
         { _courseId },
         { validate: false },
-        { projection: { _id: 1, _parentId: 1, _courseId: 1, _type: 1, _sortOrder: 1, title: 1, displayTitle: 1, _friendlyId: 1, _component: 1, _layout: 1, _menu: 1, _theme: 1, _enabledPlugins: 1, _colorLabel: 1, updatedAt: 1 } }
+        { projection: fieldsToProjection(treeFields) }
       )
       const tree = new ContentTree(items)
-      res.set('Last-Modified', lastModified.toUTCString())
+      res.set('ETag', etag)
       res.json(items.map(item => ({
         ...item,
         _children: tree.getChildren(item._id).map(c => c._id)

package/lib/utils/fieldsToProjection.js

@@ -0,0 +1,10 @@
+/**
+ * Builds a MongoDB inclusion projection from a list of field names, mapping
+ * each to `1` (e.g. `['_id', 'title']` -> `{ _id: 1, title: 1 }`). Lets a
+ * handler declare its projected fields as a readable one-per-line array.
+ * @param {Array<string>} fields Field names to include
+ * @return {Object} Inclusion projection
+ */
+export default function fieldsToProjection (fields) {
+  return Object.fromEntries((fields ?? []).map(field => [field, 1]))
+}

package/lib/utils/treeEtag.js

@@ -0,0 +1,16 @@
+import { createHash } from 'crypto'
+/**
+ * Builds a weak ETag for the content tree response. Combines the course's
+ * `updatedAt` with a hash of the projected field list, so the cache
+ * invalidates both when the course data changes AND when the tree response
+ * *shape* changes (e.g. a field is added to the projection). Keying solely on
+ * `updatedAt` served stale bodies to unedited courses after a shape change —
+ * a newly-projected field was missing until the course happened to be edited.
+ * @param {Date|string|number} updatedAt Course updatedAt
+ * @param {Array<string>} fields Projected tree field names
+ * @return {string} Weak ETag value (quoted, `W/`-prefixed)
+ */
+export default function treeEtag (updatedAt, fields) {
+  const shape = createHash('sha1').update([...(fields ?? [])].sort().join(',')).digest('hex').slice(0, 8)
+  return `W/"${new Date(updatedAt).getTime()}-${shape}"`
+}

package/lib/utils.js

@@ -3,5 +3,7 @@ export { default as buildAssetUsagePipeline } from './utils/buildAssetUsagePipel
 export { default as computeSortOrderOps } from './utils/computeSortOrderOps.js'
 export { extractAssetIds } from './utils/extractAssetIds.js'
 export { default as contentTypeToSchemaName } from './utils/contentTypeToSchemaName.js'
+export { default as fieldsToProjection } from './utils/fieldsToProjection.js'
 export { default as formatFriendlyId } from './utils/formatFriendlyId.js'
 export { default as parseMaxSeq } from './utils/parseMaxSeq.js'
+export { default as treeEtag } from './utils/treeEtag.js'

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "adapt-authoring-content",
-  "version": "3.2.2",
+  "version": "3.2.4",
   "description": "Module for managing Adapt content",
   "homepage": "https://github.com/adapt-security/adapt-authoring-content",
   "license": "GPL-3.0",

package/tests/ContentModule.spec.js

@@ -572,17 +572,24 @@ describe('ContentModule', () => {
   })
 
   describe('handleTree', () => {
-    it('should return 304 when content has not been modified', async () => {
-      const lastModified = new Date('2025-01-01T00:00:00Z')
+    it('should return 304 when the ETag matches (content + shape unchanged)', async () => {
       const inst = createInstance({
-        findOne: mock.fn(async () => ({ updatedAt: lastModified }))
+        findOne: mock.fn(async () => ({ updatedAt: new Date('2025-01-01T00:00:00Z') })),
+        find: mock.fn(async () => [])
       })
+      // capture the current ETag from a fresh request...
+      let etag
+      const firstRes = { set: mock.fn((k, v) => { if (k === 'ETag') etag = v }), json: mock.fn() }
+      await ContentModule.prototype.handleTree.call(inst, { auth: { isSuper: true }, apiData: { query: { _courseId: COURSE_ID } }, headers: {} }, firstRes, mock.fn())
+      assert.match(etag, /^W\/".+"$/)
+
+      // ...then a conditional request carrying it gets a 304
       let statusCode
       let ended = false
       const req = {
         auth: { isSuper: true },
         apiData: { query: { _courseId: COURSE_ID } },
-        headers: { 'if-modified-since': new Date('2025-01-02T00:00:00Z').toUTCString() }
+        headers: { 'if-none-match': etag }
       }
       const res = {
         status: mock.fn(function (code) { statusCode = code; return this }),
@@ -595,6 +602,31 @@ describe('ContentModule', () => {
       assert.equal(next.mock.callCount(), 0)
     })
 
+    it('should serve the tree (not 304) when the ETag no longer matches the response shape', async () => {
+      // a cached ETag from before a treeFields change must not short-circuit to
+      // 304 — otherwise the new field stays missing for unedited courses
+      const inst = createInstance({
+        findOne: mock.fn(async () => ({ updatedAt: new Date('2025-01-01T00:00:00Z') })),
+        find: mock.fn(async () => [{ _id: COURSE_ID, _type: 'course', _courseId: COURSE_ID }])
+      })
+      let statusCode
+      const req = {
+        auth: { isSuper: true },
+        apiData: { query: { _courseId: COURSE_ID } },
+        headers: { 'if-none-match': 'W/"1735689600000-deadbeef"' }
+      }
+      const res = {
+        status: mock.fn(function (code) { statusCode = code; return this }),
+        set: mock.fn(),
+        json: mock.fn()
+      }
+      const next = mock.fn()
+      await ContentModule.prototype.handleTree.call(inst, req, res, next)
+      assert.equal(statusCode, undefined, 'did not 304')
+      assert.equal(res.json.mock.callCount(), 1, 'served the tree')
+      assert.equal(next.mock.callCount(), 0)
+    })
+
     it('should return items with _children when content has been modified', async () => {
       const lastModified = new Date('2025-01-15T00:00:00Z')
       const items = [
@@ -612,9 +644,9 @@ describe('ContentModule', () => {
         headers: {}
       }
       let responseData
-      let lastModifiedHeader
+      let etagHeader
       const res = {
-        set: mock.fn((key, val) => { if (key === 'Last-Modified') lastModifiedHeader = val }),
+        set: mock.fn((key, val) => { if (key === 'ETag') etagHeader = val }),
         json: mock.fn((data) => { responseData = data })
       }
       const next = mock.fn()
@@ -631,8 +663,8 @@ describe('ContentModule', () => {
       // article should have no children
       const art = responseData.find(i => i._id === 'art1')
       assert.deepEqual(art._children, [])
-      // Last-Modified header should be set
-      assert.equal(lastModifiedHeader, lastModified.toUTCString())
+      // ETag header should be set
+      assert.match(etagHeader, /^W\/".+"$/)
     })
 
     it('should call next on error', async () => {

package/tests/utils-fieldsToProjection.spec.js

@@ -0,0 +1,22 @@
+import { describe, it } from 'node:test'
+import assert from 'node:assert/strict'
+import fieldsToProjection from '../lib/utils/fieldsToProjection.js'
+
+describe('fieldsToProjection', () => {
+  it('maps each field name to 1', () => {
+    assert.deepEqual(fieldsToProjection(['_id', 'title']), { _id: 1, title: 1 })
+  })
+
+  it('returns an empty projection for an empty array', () => {
+    assert.deepEqual(fieldsToProjection([]), {})
+  })
+
+  it('treats a missing argument as empty', () => {
+    assert.deepEqual(fieldsToProjection(), {})
+    assert.deepEqual(fieldsToProjection(undefined), {})
+  })
+
+  it('collapses duplicate field names to a single key', () => {
+    assert.deepEqual(fieldsToProjection(['_id', '_id', 'title']), { _id: 1, title: 1 })
+  })
+})

package/tests/utils-treeEtag.spec.js

@@ -0,0 +1,38 @@
+import { describe, it } from 'node:test'
+import assert from 'node:assert/strict'
+import treeEtag from '../lib/utils/treeEtag.js'
+
+const updatedAt = new Date('2026-06-18T17:34:00.123Z')
+
+describe('treeEtag', () => {
+  it('produces a quoted weak ETag', () => {
+    assert.match(treeEtag(updatedAt, ['_id', 'title']), /^W\/".+"$/)
+  })
+
+  it('is stable for the same inputs', () => {
+    assert.equal(treeEtag(updatedAt, ['_id', 'title']), treeEtag(updatedAt, ['_id', 'title']))
+  })
+
+  it('is independent of field order', () => {
+    assert.equal(treeEtag(updatedAt, ['_id', 'title']), treeEtag(updatedAt, ['title', '_id']))
+  })
+
+  it('changes when the field set changes (shape bust)', () => {
+    assert.notEqual(treeEtag(updatedAt, ['_id', 'title']), treeEtag(updatedAt, ['_id', 'title', 'heroImage']))
+  })
+
+  it('changes when updatedAt changes (data bust)', () => {
+    assert.notEqual(treeEtag(updatedAt, ['_id']), treeEtag(new Date('2026-06-19T00:00:00Z'), ['_id']))
+  })
+
+  it('accepts Date, string and numeric timestamps equivalently', () => {
+    const fields = ['_id', 'title']
+    assert.equal(treeEtag(updatedAt, fields), treeEtag(updatedAt.toISOString(), fields))
+    assert.equal(treeEtag(updatedAt, fields), treeEtag(updatedAt.getTime(), fields))
+  })
+
+  it('treats a missing field list as empty', () => {
+    assert.match(treeEtag(updatedAt), /^W\/".+"$/)
+    assert.equal(treeEtag(updatedAt), treeEtag(updatedAt, []))
+  })
+})