@nuasite/cms-core 0.56.4 → 0.57.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (56) hide show
  1. package/dist/types/astro-source-analysis.d.ts +32 -0
  2. package/dist/types/astro-source-analysis.d.ts.map +1 -0
  3. package/dist/types/check-entries.d.ts +2 -0
  4. package/dist/types/check-entries.d.ts.map +1 -1
  5. package/dist/types/check.d.ts.map +1 -1
  6. package/dist/types/collection-scanner.d.ts +22 -2
  7. package/dist/types/collection-scanner.d.ts.map +1 -1
  8. package/dist/types/content-config-ast.d.ts +76 -2
  9. package/dist/types/content-config-ast.d.ts.map +1 -1
  10. package/dist/types/core.d.ts +19 -3
  11. package/dist/types/core.d.ts.map +1 -1
  12. package/dist/types/fs/glob.d.ts +17 -0
  13. package/dist/types/fs/glob.d.ts.map +1 -1
  14. package/dist/types/fs/node-fs.d.ts.map +1 -1
  15. package/dist/types/fs/types.d.ts +30 -2
  16. package/dist/types/fs/types.d.ts.map +1 -1
  17. package/dist/types/handlers/entry-ops.d.ts.map +1 -1
  18. package/dist/types/index.d.ts +7 -5
  19. package/dist/types/index.d.ts.map +1 -1
  20. package/dist/types/media/contember.d.ts.map +1 -1
  21. package/dist/types/media/errors.d.ts +17 -0
  22. package/dist/types/media/errors.d.ts.map +1 -0
  23. package/dist/types/media/index.d.ts +3 -0
  24. package/dist/types/media/index.d.ts.map +1 -1
  25. package/dist/types/media/local.d.ts.map +1 -1
  26. package/dist/types/media/names.d.ts +17 -0
  27. package/dist/types/media/names.d.ts.map +1 -0
  28. package/dist/types/media/s3.d.ts.map +1 -1
  29. package/dist/types/media/type-filter.d.ts +67 -0
  30. package/dist/types/media/type-filter.d.ts.map +1 -0
  31. package/dist/types/project-config-ast.d.ts +5 -1
  32. package/dist/types/project-config-ast.d.ts.map +1 -1
  33. package/dist/types/route-scan.d.ts +10 -0
  34. package/dist/types/route-scan.d.ts.map +1 -0
  35. package/dist/types/tsconfig.tsbuildinfo +1 -1
  36. package/package.json +2 -2
  37. package/src/astro-source-analysis.ts +562 -0
  38. package/src/check-entries.ts +16 -1
  39. package/src/check.ts +14 -1
  40. package/src/collection-scanner.ts +413 -19
  41. package/src/content-config-ast.ts +616 -13
  42. package/src/core.ts +21 -5
  43. package/src/fs/glob.ts +39 -0
  44. package/src/fs/node-fs.ts +87 -11
  45. package/src/fs/types.ts +31 -2
  46. package/src/handlers/entry-ops.ts +11 -13
  47. package/src/index.ts +28 -3
  48. package/src/media/contember.ts +10 -2
  49. package/src/media/errors.ts +21 -0
  50. package/src/media/index.ts +10 -0
  51. package/src/media/local.ts +177 -79
  52. package/src/media/names.ts +24 -0
  53. package/src/media/s3.ts +33 -3
  54. package/src/media/type-filter.ts +186 -0
  55. package/src/project-config-ast.ts +185 -10
  56. package/src/route-scan.ts +32 -0
@@ -2,6 +2,8 @@ import type { MediaFolderItem, MediaListResult, MediaStorageAdapter, MediaUpload
2
2
  import { randomUUID } from 'node:crypto'
3
3
  import fs from 'node:fs/promises'
4
4
  import path from 'node:path'
5
+ import { MEDIA_INVALID_FOLDER, MEDIA_INVALID_ID, MEDIA_NOT_FOUND } from './errors'
6
+ import { isUnsafeFolder } from './names'
5
7
 
6
8
  export interface LocalStorageOptions {
7
9
  /**
@@ -18,113 +20,209 @@ export interface LocalStorageOptions {
18
20
  urlPrefix?: string
19
21
  }
20
22
 
23
+ /** `error.code` of a filesystem error, when it has one. */
24
+ function errorCode(error: unknown): string | undefined {
25
+ return error instanceof Error && 'code' in error && typeof error.code === 'string' ? error.code : undefined
26
+ }
27
+
28
+ /**
29
+ * A filesystem failure as a message: what was attempted and the error code. Never the
30
+ * runtime's own text, which spells out the absolute path.
31
+ */
32
+ function failure(action: string, error: unknown): string {
33
+ const code = errorCode(error)
34
+ return code ? `Failed to ${action} (${code})` : `Failed to ${action}`
35
+ }
36
+
37
+ /**
38
+ * Whether one of `names`, each taken below the one before it starting in `from`, is a
39
+ * symbolic link. Nothing here follows a link: every name is looked at with `lstat`,
40
+ * and the walk ends at the first one that is not there, since nothing below it can be
41
+ * either. Any other failure is thrown, so a name that cannot be inspected is never
42
+ * taken for a plain one.
43
+ */
44
+ async function hasSymlink(from: string, names: string[]): Promise<boolean> {
45
+ let current = from
46
+ for (const name of names) {
47
+ current += path.sep + name
48
+ try {
49
+ if ((await fs.lstat(current)).isSymbolicLink()) return true
50
+ } catch (error) {
51
+ const code = errorCode(error)
52
+ if (code === 'ENOENT' || code === 'ENOTDIR') return false
53
+ throw error
54
+ }
55
+ }
56
+ return false
57
+ }
58
+
21
59
  export function createLocalStorageAdapter(options: LocalStorageOptions = {}): MediaStorageAdapter {
22
60
  const dir = path.resolve(options.dir ?? 'public/uploads')
61
+ /** `dir` as the start of every path below it: without the separator a filesystem root ends in. */
62
+ const base = dir.endsWith(path.sep) ? dir.slice(0, -path.sep.length) : dir
23
63
  const urlPrefix = (options.urlPrefix ?? '/uploads').replace(/\/$/, '')
24
64
 
65
+ /**
66
+ * Resolve a caller-supplied id or folder to the path it names inside the uploads
67
+ * directory, or `null` when it names none. Every operation goes through here before
68
+ * it touches the filesystem.
69
+ *
70
+ * The spelling is the one `list` and `upload` hand out: names joined by `/`, none of
71
+ * them empty, `.` or `..`, and no NUL in any. Where the backslash separates paths,
72
+ * three more things make a name something other than what it spells and are refused:
73
+ * a backslash, a `:` (a drive or a stream), and a trailing dot or space (dropped by
74
+ * the system). Resolving such a path must change nothing: it is the directory
75
+ * followed by exactly these names, so it is below the directory.
76
+ *
77
+ * None of the names may be a symbolic link, wherever it points, because a link is
78
+ * the one thing that leads a path below the directory out of it. The exception is
79
+ * the last name of a file: `unlink` removes a link itself and never what it points
80
+ * to. The uploads directory and what is above it are the operator's and not looked
81
+ * at. The check is not atomic with the operation that follows it.
82
+ */
83
+ async function resolveInside(relative: string, kind: 'file' | 'folder'): Promise<string | null> {
84
+ const segments = relative.split('/')
85
+ if (relative.includes('\0') || segments.some((s) => s === '' || s === '.' || s === '..')) return null
86
+ if (path.sep === '\\' && segments.some((s) => /[\\:]|[. ]$/.test(s))) return null
87
+ const resolved = path.resolve(dir, ...segments)
88
+ if (resolved !== [base, ...segments].join(path.sep)) return null
89
+ if (await hasSymlink(base, kind === 'file' ? segments.slice(0, -1) : segments)) return null
90
+ return resolved
91
+ }
92
+
93
+ /**
94
+ * A `folder` option as the `a/b` spelling ids are built from, plus the directory it
95
+ * names: the uploads directory itself when empty, `null` when it is not inside it.
96
+ * Stray slashes are dropped (`/a//b/` is `a/b`), as `createFolder` always did.
97
+ *
98
+ * A folder to `write` into must also spell the same path once it is part of a URL
99
+ * (`isUnsafeFolder`), or the URL handed out for a file in it would address another
100
+ * one. A folder that already exists under such a name is still listed, so whatever
101
+ * is in it can be found and deleted.
102
+ */
103
+ async function resolveFolder(input: string | undefined, use: 'read' | 'write'): Promise<{ folder: string; targetDir: string } | null> {
104
+ const folder = (input ?? '').split('/').filter(Boolean).join('/')
105
+ if (!folder) return { folder, targetDir: dir }
106
+ if (use === 'write' && isUnsafeFolder(folder)) return null
107
+ const targetDir = await resolveInside(folder, 'folder')
108
+ return targetDir ? { folder, targetDir } : null
109
+ }
110
+
25
111
  return {
26
112
  staticFiles: { urlPrefix, dir },
27
113
 
28
114
  async list(opts) {
29
115
  const limit = opts?.limit ?? 50
30
116
  const offset = opts?.cursor ? parseInt(opts.cursor, 10) : 0
31
- const folder = opts?.folder ?? ''
32
-
33
- const targetDir = folder ? path.join(dir, folder) : dir
34
- await fs.mkdir(targetDir, { recursive: true })
35
-
36
- const entries = await fs.readdir(targetDir, { withFileTypes: true })
37
-
38
- const folders: MediaFolderItem[] = entries
39
- .filter((e) => e.isDirectory() && !e.name.startsWith('.'))
40
- .map((e) => ({
41
- name: e.name,
42
- path: folder ? `${folder}/${e.name}` : e.name,
43
- }))
44
- .sort((a, b) => a.name.localeCompare(b.name))
45
-
46
- const files = entries.filter((e) => e.isFile() && !e.name.startsWith('.'))
47
-
48
- const withStats = await Promise.all(
49
- files.map(async (f) => {
50
- const filePath = path.join(targetDir, f.name)
51
- const stat = await fs.stat(filePath)
52
- return { name: f.name, stat }
53
- }),
54
- )
55
- withStats.sort((a, b) => b.stat.mtimeMs - a.stat.mtimeMs)
56
-
57
- const slice = withStats.slice(offset, offset + limit)
58
- const hasMore = offset + limit < withStats.length
59
-
60
- const urlFolder = folder ? `/${folder}` : ''
61
- const items = slice.map((f) => {
62
- const ext = path.extname(f.name).toLowerCase()
63
- const contentType = mimeFromExt(ext)
117
+ const nothing: MediaListResult = { items: [], folders: [], hasMore: false }
118
+ try {
119
+ const target = await resolveFolder(opts?.folder, 'read')
120
+ if (!target) return nothing
121
+ const { folder, targetDir } = target
122
+ await fs.mkdir(targetDir, { recursive: true })
123
+
124
+ const entries = await fs.readdir(targetDir, { withFileTypes: true })
125
+
126
+ const folders: MediaFolderItem[] = entries
127
+ .filter((e) => e.isDirectory() && !e.name.startsWith('.'))
128
+ .map((e) => ({
129
+ name: e.name,
130
+ path: folder ? `${folder}/${e.name}` : e.name,
131
+ }))
132
+ .sort((a, b) => a.name.localeCompare(b.name))
133
+
134
+ const files = entries.filter((e) => e.isFile() && !e.name.startsWith('.'))
135
+
136
+ const withStats = await Promise.all(
137
+ files.map(async (f) => {
138
+ const filePath = path.join(targetDir, f.name)
139
+ const stat = await fs.stat(filePath)
140
+ return { name: f.name, stat }
141
+ }),
142
+ )
143
+ withStats.sort((a, b) => b.stat.mtimeMs - a.stat.mtimeMs)
144
+
145
+ const slice = withStats.slice(offset, offset + limit)
146
+ const hasMore = offset + limit < withStats.length
147
+
148
+ const urlFolder = folder ? `/${folder}` : ''
149
+ const items = slice.map((f) => {
150
+ const ext = path.extname(f.name).toLowerCase()
151
+ const contentType = mimeFromExt(ext)
152
+ return {
153
+ id: folder ? `${folder}/${f.name}` : f.name,
154
+ url: `${urlPrefix}${urlFolder}/${f.name}`,
155
+ filename: f.name,
156
+ contentType,
157
+ uploadedAt: f.stat.mtime.toISOString(),
158
+ folder: folder || undefined,
159
+ }
160
+ })
161
+
64
162
  return {
65
- id: folder ? `${folder}/${f.name}` : f.name,
66
- url: `${urlPrefix}${urlFolder}/${f.name}`,
67
- filename: f.name,
68
- contentType,
69
- uploadedAt: f.stat.mtime.toISOString(),
70
- folder: folder || undefined,
71
- }
72
- })
73
-
74
- return {
75
- items,
76
- folders,
77
- hasMore,
78
- cursor: hasMore ? String(offset + limit) : undefined,
79
- } satisfies MediaListResult
163
+ items,
164
+ folders,
165
+ hasMore,
166
+ cursor: hasMore ? String(offset + limit) : undefined,
167
+ } satisfies MediaListResult
168
+ } catch (error) {
169
+ // A name that belongs to a file, or is too long to be one, holds nothing to list.
170
+ const code = errorCode(error)
171
+ if (opts?.folder && (code === 'ENOTDIR' || code === 'EEXIST' || code === 'ENAMETOOLONG')) return nothing
172
+ // Deliberately without `cause`: whatever renders this error must not get the path back.
173
+ // oxlint-disable-next-line preserve-caught-error
174
+ throw new Error(failure('list media', error))
175
+ }
80
176
  },
81
177
 
82
178
  async upload(file, filename, contentType, uploadOpts) {
83
- const folder = uploadOpts?.folder ?? ''
84
- const targetDir = folder ? path.join(dir, folder) : dir
85
- await fs.mkdir(targetDir, { recursive: true })
86
-
87
- const ext = getFileExtension(filename)
88
- const uuid = randomUUID()
89
- const newFilename = `${uuid}${ext ? `.${ext}` : ''}`
90
- const filePath = path.join(targetDir, newFilename)
91
-
92
- await fs.writeFile(filePath, file)
93
-
94
- const urlFolder = folder ? `/${folder}` : ''
95
- const id = folder ? `${folder}/${newFilename}` : newFilename
96
-
97
- return {
98
- success: true,
99
- url: `${urlPrefix}${urlFolder}/${newFilename}`,
100
- filename: newFilename,
101
- id,
102
- } satisfies MediaUploadResult
179
+ try {
180
+ const target = await resolveFolder(uploadOpts?.folder, 'write')
181
+ if (!target) return { success: false, error: MEDIA_INVALID_FOLDER }
182
+ const { folder, targetDir } = target
183
+ await fs.mkdir(targetDir, { recursive: true })
184
+
185
+ const ext = getFileExtension(filename)
186
+ const uuid = randomUUID()
187
+ const newFilename = `${uuid}${ext ? `.${ext}` : ''}`
188
+ const filePath = path.join(targetDir, newFilename)
189
+
190
+ await fs.writeFile(filePath, file)
191
+
192
+ const urlFolder = folder ? `/${folder}` : ''
193
+ const id = folder ? `${folder}/${newFilename}` : newFilename
194
+
195
+ return {
196
+ success: true,
197
+ url: `${urlPrefix}${urlFolder}/${newFilename}`,
198
+ filename: newFilename,
199
+ id,
200
+ } satisfies MediaUploadResult
201
+ } catch (error) {
202
+ return { success: false, error: failure('store media file', error) }
203
+ }
103
204
  },
104
205
 
105
206
  async delete(id) {
106
- const safePath = id.split('/').map((s) => path.basename(s)).join('/')
107
- const filePath = path.join(dir, safePath)
108
207
  try {
208
+ const filePath = await resolveInside(id, 'file')
209
+ if (!filePath) return { success: false, error: MEDIA_INVALID_ID }
109
210
  await fs.unlink(filePath)
110
211
  return { success: true }
111
212
  } catch (error) {
112
- const message = error instanceof Error ? error.message : String(error)
113
- return { success: false, error: message }
213
+ if (errorCode(error) === 'ENOENT') return { success: false, error: MEDIA_NOT_FOUND }
214
+ return { success: false, error: failure('delete media file', error) }
114
215
  }
115
216
  },
116
217
 
117
218
  async createFolder(folder) {
118
- const segments = folder.split('/').filter(Boolean)
119
- if (segments.some((s) => s === '..' || s === '.')) {
120
- return { success: false, error: 'Invalid folder name' }
121
- }
122
219
  try {
123
- await fs.mkdir(path.join(dir, ...segments), { recursive: true })
220
+ const target = await resolveFolder(folder, 'write')
221
+ if (!target) return { success: false, error: MEDIA_INVALID_FOLDER }
222
+ await fs.mkdir(target.targetDir, { recursive: true })
124
223
  return { success: true }
125
224
  } catch (error) {
126
- const message = error instanceof Error ? error.message : String(error)
127
- return { success: false, error: message }
225
+ return { success: false, error: failure('create folder', error) }
128
226
  }
129
227
  },
130
228
  }
@@ -0,0 +1,24 @@
1
+ /**
2
+ * Whether a `/`-separated name holds a `.` or `..` segment as it is spelled. These are
3
+ * the segments a path resolves away.
4
+ */
5
+ export function hasDotSegment(value: string): boolean {
6
+ return value.split('/').some((s) => s === '.' || s === '..')
7
+ }
8
+
9
+ /**
10
+ * Whether a folder a caller asks to create or upload into would turn into something
11
+ * else once it is part of a URL. A URL parser reads a segment spelled `%2e`, `.%2e`,
12
+ * `%2e.` or `%2e%2e` (in any case) as `.` or `..`, and a backslash as `/`, so the URL
13
+ * built for a file in such a folder would address a different path than the one the
14
+ * file was stored at. Literal `.` and `..` segments count too.
15
+ *
16
+ * Only new folders are held to this: an id or folder that already exists in storage is
17
+ * still listed and deleted as it is spelled.
18
+ */
19
+ export function isUnsafeFolder(folder: string): boolean {
20
+ return folder.includes('\\') || folder.split('/').some((s) => {
21
+ const decoded = s.replace(/%2e/gi, '.')
22
+ return decoded === '.' || decoded === '..'
23
+ })
24
+ }
package/src/media/s3.ts CHANGED
@@ -1,7 +1,26 @@
1
1
  import type { MediaFolderItem, MediaListResult, MediaStorageAdapter, MediaUploadResult } from '@nuasite/cms-types'
2
2
  import { randomUUID } from 'node:crypto'
3
3
  import path from 'node:path'
4
+ import { MEDIA_INVALID_FOLDER, MEDIA_INVALID_ID } from './errors'
4
5
  import { getFileExtension, mimeFromExt } from './local'
6
+ import { hasDotSegment, isUnsafeFolder } from './names'
7
+
8
+ /*
9
+ * S3 keys are literal, so `.` and `..` name nothing special there. Whatever sits in
10
+ * front of the bucket (a CDN, a proxy, the URL built from the key) may still resolve
11
+ * them, so the adapter neither builds nor accepts one in what a caller supplies: a
12
+ * folder (spelled out, percent-encoded or with a backslash, see `isUnsafeFolder`), or
13
+ * the part of a key after the configured prefix.
14
+ */
15
+
16
+ /**
17
+ * A `folder` option as the `a/b` spelling keys are built from. Stray slashes are dropped
18
+ * (`/a//b/` is `a/b`), as the local adapter does, so no key `upload` hands out holds an
19
+ * empty segment that `delete` would refuse.
20
+ */
21
+ function normalizeFolder(folder: string | undefined): string {
22
+ return (folder ?? '').split('/').filter(Boolean).join('/')
23
+ }
5
24
 
6
25
  export interface S3StorageOptions {
7
26
  bucket: string
@@ -53,7 +72,8 @@ export function createS3StorageAdapter(options: S3StorageOptions): MediaStorageA
53
72
  const client = await getClient()
54
73
 
55
74
  const limit = opts?.limit ?? 50
56
- const folder = opts?.folder ?? ''
75
+ const folder = normalizeFolder(opts?.folder)
76
+ if (isUnsafeFolder(folder)) return { items: [], folders: [], hasMore: false } satisfies MediaListResult
57
77
 
58
78
  const listPrefix = [prefix, folder].filter(Boolean).join('/')
59
79
  const delimiterPrefix = listPrefix ? `${listPrefix}/` : ''
@@ -103,13 +123,14 @@ export function createS3StorageAdapter(options: S3StorageOptions): MediaStorageA
103
123
  },
104
124
 
105
125
  async upload(file, filename, contentType, uploadOpts) {
126
+ const folder = normalizeFolder(uploadOpts?.folder)
127
+ if (isUnsafeFolder(folder)) return { success: false, error: MEDIA_INVALID_FOLDER }
106
128
  const { PutObjectCommand } = await loadS3()
107
129
  const client = await getClient()
108
130
 
109
131
  const ext = getFileExtension(filename)
110
132
  const uuid = randomUUID()
111
133
  const newFilename = `${uuid}${ext ? `.${ext}` : ''}`
112
- const folder = uploadOpts?.folder ?? ''
113
134
  const keyParts = [prefix, folder, newFilename].filter(Boolean)
114
135
  const key = keyParts.join('/')
115
136
 
@@ -131,6 +152,13 @@ export function createS3StorageAdapter(options: S3StorageOptions): MediaStorageA
131
152
  },
132
153
 
133
154
  async delete(id) {
155
+ // An id is the object key `list` and `upload` hand out, so it always sits under the
156
+ // configured prefix. Anything else in the bucket is not this adapter's to remove.
157
+ // The prefix is the operator's and taken as configured; only what follows it is checked.
158
+ // What follows it names an object: not empty, and no empty, `.` or `..` segment in it.
159
+ if (prefix && !id.startsWith(`${prefix}/`)) return { success: false, error: MEDIA_INVALID_ID }
160
+ const rest = prefix ? id.slice(prefix.length + 1) : id
161
+ if (rest.split('/').includes('') || hasDotSegment(rest)) return { success: false, error: MEDIA_INVALID_ID }
134
162
  try {
135
163
  const { DeleteObjectCommand } = await loadS3()
136
164
  const client = await getClient()
@@ -143,8 +171,10 @@ export function createS3StorageAdapter(options: S3StorageOptions): MediaStorageA
143
171
  await client.send(command)
144
172
  return { success: true }
145
173
  } catch (error) {
174
+ // Prefixed, so no text the SDK or the service comes up with can pass for one of the
175
+ // adapter's own refusals.
146
176
  const message = error instanceof Error ? error.message : String(error)
147
- return { success: false, error: message }
177
+ return { success: false, error: `Delete failed: ${message}` }
148
178
  }
149
179
  },
150
180
  }
@@ -0,0 +1,186 @@
1
+ import {
2
+ matchesMediaType,
3
+ type MediaFolderItem,
4
+ type MediaItem,
5
+ type MediaListOptions,
6
+ type MediaListResult,
7
+ type MediaTypeFilter,
8
+ } from '@nuasite/cms-types'
9
+
10
+ /** The value of a `?type=` parameter, or `null` when it names no tab we know. */
11
+ export function parseMediaTypeFilter(raw: string | null | undefined): MediaTypeFilter | null {
12
+ if (raw === null || raw === undefined || raw === '') return 'all'
13
+ return raw === 'all' || raw === 'photo' || raw === 'graphic' || raw === 'video' || raw === 'document' ? raw : null
14
+ }
15
+
16
+ /**
17
+ * A cursor `listFilteredMedia` refused: not one it minted, or minted under a different tab. A host
18
+ * answers it with a 400 and the message, never by listing from the start.
19
+ */
20
+ export class MediaCursorError extends Error {
21
+ override name = 'MediaCursorError'
22
+ }
23
+
24
+ export const MEDIA_INVALID_CURSOR = 'Invalid media cursor'
25
+ export const MEDIA_CURSOR_TYPE_MISMATCH =
26
+ 'This cursor continues a listing filtered by a different ?type=. Start the listing again when the filter changes'
27
+
28
+ /**
29
+ * Where a filtered listing continues: the source page that `source` (the source's own cursor,
30
+ * absent for its first page) fetches at `size` items, from its `skip`-th item on. A filtered page
31
+ * that fills up halfway through a source page ends there, and this is how the next one starts at
32
+ * the item after, rather than at the next source page with the rest of this one lost.
33
+ */
34
+ interface FilteredPosition {
35
+ source: string | undefined
36
+ skip: number
37
+ size: number
38
+ }
39
+
40
+ const FILTERED_CURSOR_VERSION = 1
41
+
42
+ function toBase64Url(text: string): string {
43
+ let binary = ''
44
+ for (const byte of new TextEncoder().encode(text)) binary += String.fromCharCode(byte)
45
+ return btoa(binary).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '')
46
+ }
47
+
48
+ function fromBase64Url(raw: string): string {
49
+ const binary = atob(raw.replace(/-/g, '+').replace(/_/g, '/'))
50
+ return new TextDecoder().decode(Uint8Array.from(binary, char => char.charCodeAt(0)))
51
+ }
52
+
53
+ function encodeFilteredCursor(position: FilteredPosition, type: MediaTypeFilter): string {
54
+ const { source, skip, size } = position
55
+ return toBase64Url(JSON.stringify({ fv: FILTERED_CURSOR_VERSION, type, source, skip, size }))
56
+ }
57
+
58
+ /**
59
+ * The tab and position a filtered cursor carries, or `null` when `raw` is not one `listFilteredMedia`
60
+ * minted. A host that also serves unfiltered listings uses it to refuse one followed without its
61
+ * `?type=`, which the adapter would otherwise read as its own cursor.
62
+ */
63
+ export function decodeFilteredMediaCursor(raw: string): (FilteredPosition & { type: MediaTypeFilter }) | null {
64
+ let parsed: unknown
65
+ try {
66
+ parsed = JSON.parse(fromBase64Url(raw))
67
+ } catch {
68
+ return null
69
+ }
70
+ if (typeof parsed !== 'object' || parsed === null || !('fv' in parsed) || parsed.fv !== FILTERED_CURSOR_VERSION) return null
71
+ const type = 'type' in parsed && typeof parsed.type === 'string' ? parseMediaTypeFilter(parsed.type) : null
72
+ if (type === null || type === 'all') return null
73
+ const source = 'source' in parsed ? parsed.source : undefined
74
+ if (source !== undefined && typeof source !== 'string') return null
75
+ const skip = 'skip' in parsed ? parsed.skip : undefined
76
+ const size = 'size' in parsed ? parsed.size : undefined
77
+ if (typeof skip !== 'number' || !Number.isSafeInteger(skip) || skip < 0) return null
78
+ // The cursor travels through the client, so its size is held to what this module would mint:
79
+ // otherwise a forged one asks the source for any number of items, past every `limit` clamp.
80
+ if (typeof size !== 'number' || !Number.isSafeInteger(size) || size < MIN_SOURCE_PAGE || size > MAX_FILTERED_MEDIA_LIMIT) return null
81
+ if (skip > size) return null
82
+ return { type, source, skip, size }
83
+ }
84
+
85
+ /**
86
+ * The smallest source page a filtered listing reads. A tab that matches one item in ten would
87
+ * otherwise spend a source round trip per handful of matches, and against the local adapter each
88
+ * round trip re-reads the whole folder.
89
+ */
90
+ const MIN_SOURCE_PAGE = 200
91
+
92
+ /**
93
+ * The largest filtered page, and so the largest source page. The same bound both HTTP layers put on
94
+ * an unfiltered `limit`, applied here again so a caller that forgets to clamp cannot widen the scan.
95
+ */
96
+ export const MAX_FILTERED_MEDIA_LIMIT = 1000
97
+
98
+ /**
99
+ * Source items one filtered page may ask for, all pages together: twenty pages at the smallest
100
+ * source page. A "Documents" tab over a library of photos matches nothing, and without a bound
101
+ * that is a walk of the whole library in a single request.
102
+ */
103
+ const MAX_SCANNED = 20 * MIN_SOURCE_PAGE
104
+
105
+ /** `limit` held to `[1, MAX_FILTERED_MEDIA_LIMIT]`; one that is not a finite number sets no target. */
106
+ function clampLimit(limit: number | undefined): number | undefined {
107
+ if (limit === undefined || !Number.isFinite(limit)) return undefined
108
+ return Math.min(Math.max(Math.floor(limit), 1), MAX_FILTERED_MEDIA_LIMIT)
109
+ }
110
+
111
+ /**
112
+ * One page of a cursor-paged listing, filtered to `type`.
113
+ *
114
+ * A filter cannot be pushed into the adapters: they page over a filesystem, a bucket or a remote
115
+ * API, each with its own cursor. So it is applied here, above whichever one answered, by pulling
116
+ * further pages until this one is full. That keeps the cost of a filter inside a single request:
117
+ * without it the client is the one that drains, one round trip per page, and every round trip that
118
+ * reaches the sidecar's project scan makes it re-walk the project.
119
+ *
120
+ * A filtered page holds at most `limit` items. The source is read at `max(limit, 200)` items a
121
+ * page, so a page usually fills halfway through a source page; the cursor it hands back is one of
122
+ * ours, bound to `type`, and resumes by re-reading that source page and skipping what was already
123
+ * listed. That relies on a source answering the same cursor and size with the same page, which an
124
+ * offset or continuation-token listing does as long as nothing is written in between: the same
125
+ * caveat any offset pager carries. An unfiltered listing is passed straight through, the source's
126
+ * own cursor included.
127
+ *
128
+ * A cursor this did not mint, or minted under another tab, throws `MediaCursorError`.
129
+ * `hasMore` can be true on a page short of `limit`: that is what the scan bound below leaves behind.
130
+ */
131
+ export async function listFilteredMedia(
132
+ list: (options: MediaListOptions) => Promise<MediaListResult>,
133
+ options: MediaListOptions & { type?: MediaTypeFilter },
134
+ /**
135
+ * How many source items one filtered page may ask for, counted as the larger of what each source
136
+ * page was asked for and what it returned. Reaching it just ends the page early. `hasMore` still
137
+ * says there is more, so the caller can ask again. The first source page is always read.
138
+ */
139
+ maxScanned = MAX_SCANNED,
140
+ ): Promise<MediaListResult> {
141
+ const type = options.type ?? 'all'
142
+ if (type === 'all') return await list(options)
143
+
144
+ const limit = clampLimit(options.limit)
145
+ let position: FilteredPosition = { source: undefined, skip: 0, size: Math.max(limit ?? 0, MIN_SOURCE_PAGE) }
146
+ if (options.cursor !== undefined) {
147
+ const decoded = decodeFilteredMediaCursor(options.cursor)
148
+ if (decoded === null) throw new MediaCursorError(MEDIA_INVALID_CURSOR)
149
+ if (decoded.type !== type) throw new MediaCursorError(MEDIA_CURSOR_TYPE_MISMATCH)
150
+ position = decoded
151
+ }
152
+
153
+ const items: MediaItem[] = []
154
+ let folders: MediaFolderItem[] | undefined
155
+ const done = (hasMore: boolean, next: FilteredPosition | undefined): MediaListResult => ({
156
+ items,
157
+ folders: folders ?? [],
158
+ hasMore,
159
+ cursor: next === undefined ? undefined : encodeFilteredCursor(next, type),
160
+ appliedType: type,
161
+ })
162
+
163
+ for (let scanned = 0;;) {
164
+ const page = await list({ ...options, cursor: position.source, limit: position.size })
165
+ folders ??= page.folders
166
+ const pageItems = page.items
167
+ scanned += Math.max(position.size, pageItems.length)
168
+ for (let index = position.skip; index < pageItems.length; index++) {
169
+ const item = pageItems[index]
170
+ if (item === undefined || !matchesMediaType(item.contentType, type)) continue
171
+ items.push(item)
172
+ if (limit === undefined || items.length < limit) continue
173
+ // Full. Stop at this item when the source page still holds a match after it; otherwise
174
+ // the page is spent and the listing continues the way the source does.
175
+ const matchesLeft = pageItems.slice(index + 1).some(later => matchesMediaType(later.contentType, type))
176
+ if (matchesLeft) return done(true, { ...position, skip: index + 1 })
177
+ break
178
+ }
179
+ const next = page.hasMore && page.cursor !== undefined ? { source: page.cursor, skip: 0, size: position.size } : undefined
180
+ const full = limit !== undefined && items.length >= limit
181
+ // An adapter that reports more but hands back no cursor cannot be advanced: say there is more
182
+ // anyway, with no cursor, rather than claim the listing ended.
183
+ if (full || next === undefined || scanned >= maxScanned) return done(page.hasMore, next)
184
+ position = next
185
+ }
186
+ }