adapt-authoring-content 3.2.3 → 3.3.0

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, fieldsToProjection, 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,12 +679,6 @@ 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) {
-        return res.status(304).end()
-      }
       const treeFields = [
         '_id',
         '_parentId',
@@ -700,16 +694,25 @@ class ContentModule extends AbstractApiModule {
         '_theme',
         '_enabledPlugins',
         '_colorLabel',
+        '_language',
         '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: 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/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

@@ -6,3 +6,4 @@ export { default as contentTypeToSchemaName } from './utils/contentTypeToSchemaN
 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.3",
+  "version": "3.3.0",
   "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-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, []))
+  })
+})

package/tests/_ht.js

@@ -1,116 +0,0 @@
-import { describe, it, mock } from 'node:test'
-import assert from 'node:assert/strict'
-
-import ContentModule from '../lib/ContentModule.js'
-
-const COURSE_ID = '507f1f77bcf86cd799439011'
-
-function createMockCollection (overrides = {}) {
-  return {
-    findOne: mock.fn(async () => null),
-    updateOne: mock.fn(async () => {}),
-    findOneAndUpdate: mock.fn(async () => ({ seq: 1 })),
-    find: mock.fn(() => ({ toArray: mock.fn(async () => []) })),
-    deleteMany: mock.fn(async () => {}),
-    ...overrides
-  }
-}
-
-function createMockMongodb (collectionOverrides) {
-  const col = createMockCollection(collectionOverrides)
-  return { getCollection: mock.fn(() => col), collection: col }
-}
-
-function createInstance (overrides = {}) {
-  return {
-    schemaName: 'content',
-    collectionName: 'content',
-    counterCollectionName: 'contentcounters',
-    idInterval: 5,
-    contentplugin: { findOne: mock.fn(async () => null) },
-    jsonschema: { extendSchema: mock.fn() },
-    authored: { schemaName: 'authored' },
-    tags: { schemaExtensionName: 'tags' },
-    mongodb: createMockMongodb(),
-    find: mock.fn(async () => []),
-    findOne: mock.fn(async () => null),
-    ...overrides
-  }
-}
-
-describe('ContentModule', () => {
-  describe('handleTree', () => {
-    it('should return 304 when content has not been modified', async () => {
-      const lastModified = new Date('2025-01-01T00:00:00Z')
-      const inst = createInstance({
-        findOne: mock.fn(async () => ({ updatedAt: lastModified }))
-      })
-      let statusCode
-      let ended = false
-      const req = {
-        apiData: { query: { _courseId: COURSE_ID } },
-        headers: { 'if-modified-since': new Date('2025-01-02T00:00:00Z').toUTCString() }
-      }
-      const res = {
-        status: mock.fn(function (code) { statusCode = code; return this }),
-        end: mock.fn(() => { ended = true })
-      }
-      const next = mock.fn()
-      await ContentModule.prototype.handleTree.call(inst, req, res, next)
-      assert.equal(statusCode, 304)
-      assert.equal(ended, true)
-      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 = [
-        { _id: COURSE_ID, _type: 'course', _courseId: COURSE_ID },
-        { _id: 'page1', _type: 'page', _parentId: COURSE_ID, _courseId: COURSE_ID },
-        { _id: 'art1', _type: 'article', _parentId: 'page1', _courseId: COURSE_ID }
-      ]
-      const inst = createInstance({
-        findOne: mock.fn(async () => ({ updatedAt: lastModified })),
-        find: mock.fn(async () => items)
-      })
-      const req = {
-        apiData: { query: { _courseId: COURSE_ID } },
-        headers: {}
-      }
-      let responseData
-      let lastModifiedHeader
-      const res = {
-        set: mock.fn((key, val) => { if (key === 'Last-Modified') lastModifiedHeader = val }),
-        json: mock.fn((data) => { responseData = data })
-      }
-      const next = mock.fn()
-      await ContentModule.prototype.handleTree.call(inst, req, res, next)
-
-      assert.equal(next.mock.callCount(), 0)
-      assert.equal(responseData.length, 3)
-      // course should have page1 as child
-      const course = responseData.find(i => i._id === COURSE_ID)
-      assert.deepEqual(course._children, ['page1'])
-      // page should have art1 as child
-      const page = responseData.find(i => i._id === 'page1')
-      assert.deepEqual(page._children, ['art1'])
-      // 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())
-    })
-
-    it('should call next on error', async () => {
-      const inst = createInstance({
-        findOne: mock.fn(async () => { throw new Error('db error') })
-      })
-      const req = { apiData: { query: { _courseId: COURSE_ID } }, headers: {} }
-      const res = {}
-      const next = mock.fn()
-      await ContentModule.prototype.handleTree.call(inst, req, res, next)
-      assert.equal(next.mock.callCount(), 1)
-      assert.equal(next.mock.calls[0].arguments[0].message, 'db error')
-    })
-  })
-})