@nuasite/cms-core 0.56.4 → 0.58.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.
- package/dist/types/astro-source-analysis.d.ts +32 -0
- package/dist/types/astro-source-analysis.d.ts.map +1 -0
- package/dist/types/check-entries.d.ts +2 -0
- package/dist/types/check-entries.d.ts.map +1 -1
- package/dist/types/check.d.ts.map +1 -1
- package/dist/types/collection-scanner.d.ts +22 -2
- package/dist/types/collection-scanner.d.ts.map +1 -1
- package/dist/types/content-config-ast.d.ts +76 -2
- package/dist/types/content-config-ast.d.ts.map +1 -1
- package/dist/types/core.d.ts +19 -3
- package/dist/types/core.d.ts.map +1 -1
- package/dist/types/fs/glob.d.ts +17 -0
- package/dist/types/fs/glob.d.ts.map +1 -1
- package/dist/types/fs/node-fs.d.ts.map +1 -1
- package/dist/types/fs/types.d.ts +30 -2
- package/dist/types/fs/types.d.ts.map +1 -1
- package/dist/types/handlers/entry-ops.d.ts.map +1 -1
- package/dist/types/index.d.ts +7 -5
- package/dist/types/index.d.ts.map +1 -1
- package/dist/types/media/contember.d.ts.map +1 -1
- package/dist/types/media/errors.d.ts +17 -0
- package/dist/types/media/errors.d.ts.map +1 -0
- package/dist/types/media/index.d.ts +3 -0
- package/dist/types/media/index.d.ts.map +1 -1
- package/dist/types/media/local.d.ts.map +1 -1
- package/dist/types/media/names.d.ts +17 -0
- package/dist/types/media/names.d.ts.map +1 -0
- package/dist/types/media/s3.d.ts.map +1 -1
- package/dist/types/media/type-filter.d.ts +67 -0
- package/dist/types/media/type-filter.d.ts.map +1 -0
- package/dist/types/project-config-ast.d.ts +5 -1
- package/dist/types/project-config-ast.d.ts.map +1 -1
- package/dist/types/route-scan.d.ts +10 -0
- package/dist/types/route-scan.d.ts.map +1 -0
- package/dist/types/tsconfig.tsbuildinfo +1 -1
- package/package.json +2 -2
- package/src/astro-source-analysis.ts +562 -0
- package/src/check-entries.ts +16 -1
- package/src/check.ts +14 -1
- package/src/collection-scanner.ts +413 -19
- package/src/content-config-ast.ts +616 -13
- package/src/core.ts +21 -5
- package/src/fs/glob.ts +39 -0
- package/src/fs/node-fs.ts +87 -11
- package/src/fs/types.ts +31 -2
- package/src/handlers/entry-ops.ts +11 -13
- package/src/index.ts +28 -3
- package/src/media/contember.ts +10 -2
- package/src/media/errors.ts +21 -0
- package/src/media/index.ts +10 -0
- package/src/media/local.ts +177 -79
- package/src/media/names.ts +24 -0
- package/src/media/s3.ts +33 -3
- package/src/media/type-filter.ts +186 -0
- package/src/project-config-ast.ts +185 -10
- package/src/route-scan.ts +32 -0
package/src/media/local.ts
CHANGED
|
@@ -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
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
const
|
|
63
|
-
const
|
|
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
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
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
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
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
|
-
|
|
113
|
-
return { success: false, error:
|
|
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
|
|
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
|
-
|
|
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
|
+
}
|