Mark protocol versions as generated

.github/workflows/ci.yml

@@ -40,6 +40,17 @@ jobs:
           deno-version: latest
       - name: Install dependencies
         run: npm ci
+      - name: Configure Puppeteer browser
+        if: matrix.suite == 'puppeteer'
+        run: |
+          chrome_bin="$(command -v google-chrome || command -v google-chrome-stable || command -v chromium-browser || true)"
+          if [ -z "$chrome_bin" ]; then
+            rm -rf ~/.cache/puppeteer/chrome
+            npx puppeteer browsers install chrome
+            chrome_bin="$(node -e "process.stdout.write(require('puppeteer').executablePath())")"
+          fi
+          test -x "$chrome_bin"
+          echo "CHROME_BIN=$chrome_bin" >> "$GITHUB_ENV"
       - name: Build
         run: npm run build
       - name: Test

examples/api2-devdock-transloadit-assembly-upload/main.js

@@ -0,0 +1,165 @@
+import { readFile, writeFile } from 'node:fs/promises'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+import { Upload } from '../../lib.esm/node/index.js'
+
+function fail(message) {
+  throw new Error(message)
+}
+
+function exampleDirname() {
+  return path.dirname(fileURLToPath(import.meta.url))
+}
+
+async function loadScenario() {
+  const scenarioPath =
+    process.env.API2_SDK_EXAMPLE_SCENARIO ?? path.join(exampleDirname(), 'api2-scenario.json')
+
+  return JSON.parse(await readFile(scenarioPath, 'utf8'))
+}
+
+function readPath(value, pathParts, label) {
+  let current = value
+  for (const part of pathParts) {
+    if (Array.isArray(current) && Number.isInteger(part)) {
+      if (part >= current.length) {
+        fail(`${label} path ${JSON.stringify(pathParts)} index ${part} is out of range`)
+      }
+      current = current[part]
+      continue
+    }
+
+    if (
+      typeof current === 'object' &&
+      current !== null &&
+      !Array.isArray(current) &&
+      typeof part === 'string'
+    ) {
+      if (!Object.hasOwn(current, part)) {
+        fail(`${label} path ${JSON.stringify(pathParts)} is missing key ${JSON.stringify(part)}`)
+      }
+      current = current[part]
+      continue
+    }
+
+    fail(`${label} path ${JSON.stringify(pathParts)} cannot read ${JSON.stringify(part)}`)
+  }
+
+  return current
+}
+
+function resolveValue(valueSpec, context, label) {
+  if (Object.hasOwn(valueSpec, 'value')) {
+    return valueSpec.value
+  }
+
+  const source = valueSpec.source
+  if (typeof source !== 'object' || source === null || Array.isArray(source)) {
+    fail(`${label} value spec has no literal value or source`)
+  }
+
+  if (!Object.hasOwn(context, source.root)) {
+    fail(`${label} value source root ${JSON.stringify(source.root)} is unavailable`)
+  }
+
+  if (!Array.isArray(source.path)) {
+    fail(`${label} value source path must be an array`)
+  }
+
+  return readPath(context[source.root], source.path, label)
+}
+
+function scalarString(value) {
+  if (value === null) {
+    return 'null'
+  }
+
+  if (typeof value === 'boolean') {
+    return value ? 'true' : 'false'
+  }
+
+  return String(value)
+}
+
+function scenarioBytes(uploadConfig) {
+  const source = uploadConfig.source
+  if (source.kind !== 'bytes') {
+    fail(`unsupported scenario source kind ${JSON.stringify(source.kind)}`)
+  }
+
+  if (source.encoding !== 'utf8') {
+    fail(`unsupported scenario source encoding ${JSON.stringify(source.encoding)}`)
+  }
+
+  return Buffer.from(source.value, 'utf8')
+}
+
+function uploadMetadata(uploadConfig, scenario, createResponse) {
+  const context = { createResponse, scenario }
+  const metadata = {}
+  for (const field of uploadConfig.metadata) {
+    metadata[field.name] = scalarString(resolveValue(field.value, context, field.name))
+  }
+
+  return metadata
+}
+
+function retryDelays(retries) {
+  if (!Number.isInteger(retries) || retries < 0) {
+    fail(`unsupported retry count ${JSON.stringify(retries)}`)
+  }
+
+  return Array.from({ length: retries }, () => 0)
+}
+
+async function uploadWithTus(scenario, createResponse) {
+  const uploadConfig = scenario.upload
+  const context = { createResponse, scenario }
+  const endpoint = scalarString(resolveValue(uploadConfig.tusUrl, context, 'tusUrl'))
+  const content = scenarioBytes(uploadConfig)
+  if (uploadConfig.chunkSize !== 'full-file') {
+    fail(`unsupported chunk size policy ${JSON.stringify(uploadConfig.chunkSize)}`)
+  }
+
+  const upload = new Upload(content, {
+    endpoint,
+    chunkSize: content.length,
+    metadata: uploadMetadata(uploadConfig, scenario, createResponse),
+    retryDelays: retryDelays(uploadConfig.retries),
+  })
+
+  await new Promise((resolve, reject) => {
+    upload.options.onError = reject
+    upload.options.onSuccess = resolve
+    upload.start()
+  })
+
+  if (!upload.url) {
+    fail('TUS upload did not expose an upload URL')
+  }
+
+  return upload.url
+}
+
+async function writeResult(uploadUrl) {
+  const resultPath = process.env.API2_SDK_EXAMPLE_RESULT
+  if (!resultPath) {
+    return
+  }
+
+  await writeFile(resultPath, `${JSON.stringify({ uploadUrl }, undefined, 2)}\n`)
+}
+
+async function main() {
+  const scenario = await loadScenario()
+  const createResponse = scenario.prepared.createResponse
+  const uploadUrl = await uploadWithTus(scenario, createResponse)
+  await writeResult(uploadUrl)
+  console.log(`TypeScript TUS SDK devdock scenario ${scenario.scenarioId} uploaded to ${uploadUrl}`)
+}
+
+main().catch((err) => {
+  console.error(err)
+  process.exit(1)
+})

lib/DetailedError.ts

@@ -1,4 +1,11 @@
 import type { HttpRequest, HttpResponse } from './options.js'
+import type { TusDetailedErrorRequestContext } from './protocol_generated.js'
+import {
+  TUS_REQUEST_ID_HEADER_NAME,
+  tusDetailedErrorEmptyResponseBody,
+  tusDetailedErrorMessage,
+  tusDetailedErrorMissingValue,
+} from './protocol_generated.js'
 
 export class DetailedError extends Error {
   originalRequest?: HttpRequest
@@ -14,18 +21,23 @@ export class DetailedError extends Error {
     this.originalResponse = res
     this.causingError = causingErr
 
-    if (causingErr != null) {
-      message += `, caused by ${causingErr.toString()}`
-    }
-
+    let requestContext: TusDetailedErrorRequestContext | undefined
     if (req != null) {
-      const requestId = req.getHeader('X-Request-ID') || 'n/a'
-      const method = req.getMethod()
-      const url = req.getURL()
-      const status = res ? res.getStatus() : 'n/a'
-      const body = res ? res.getBody() || '' : 'n/a'
-      message += `, originated from request (method: ${method}, url: ${url}, response code: ${status}, response text: ${body}, request id: ${requestId})`
+      requestContext = {
+        body: res
+          ? res.getBody() || tusDetailedErrorEmptyResponseBody()
+          : tusDetailedErrorMissingValue(),
+        method: req.getMethod(),
+        requestId: req.getHeader(TUS_REQUEST_ID_HEADER_NAME) || tusDetailedErrorMissingValue(),
+        status: res ? res.getStatus() : tusDetailedErrorMissingValue(),
+        url: req.getURL(),
+      }
     }
-    this.message = message
+
+    this.message = tusDetailedErrorMessage({
+      baseMessage: message,
+      cause: causingErr?.toString(),
+      requestContext,
+    })
   }
 }

lib/browser/BrowserFileReader.ts

@@ -1,8 +1,11 @@
-import {
-  openFile as openBaseFile,
-  supportedTypes as supportedBaseTypes,
-} from '../commonFileReader.js'
+import { openFile as openBaseFile } from '../commonFileReader.js'
 import type { FileReader, FileSource, UploadInput } from '../options.js'
+import {
+  tusCommonSupportedFileSourceTypes,
+  tusReactNativeUriBlobFetchFailedMessage,
+  tusReactNativeUriUnsupportedMessage,
+  tusUnsupportedSourceTypeMessage,
+} from '../protocol_generated.js'
 import { isReactNativeFile, isReactNativePlatform } from '../reactnative/isReactNative.js'
 import { uriToBlob } from '../reactnative/uriToBlob.js'
 import { BlobFileSource } from '../sources/BlobFileSource.js'
@@ -15,24 +18,24 @@ export class BrowserFileReader implements FileReader {
     // the file blob, before uploading with tus.
     if (isReactNativeFile(input)) {
       if (!isReactNativePlatform()) {
-        throw new Error('tus: file objects with `uri` property is only supported in React Native')
+        throw new Error(tusReactNativeUriUnsupportedMessage())
       }
 
       try {
         const blob = await uriToBlob(input.uri)
         return new BlobFileSource(blob)
       } catch (err) {
-        throw new Error(
-          `tus: cannot fetch \`file.uri\` as Blob, make sure the uri is correct and accessible. ${err}`,
-        )
+        throw new Error(tusReactNativeUriBlobFetchFailedMessage({ error: err }))
       }
     }
 
     const fileSource = openBaseFile(input, chunkSize)
     if (fileSource) return fileSource
 
     throw new Error(
-      `in this environment the source object may only be an instance of: ${supportedBaseTypes.join(', ')}`,
+      tusUnsupportedSourceTypeMessage({
+        supportedTypes: tusCommonSupportedFileSourceTypes(),
+      }),
     )
   }
 }

lib/browser/FetchHttpStack.ts

@@ -6,6 +6,7 @@ import type {
   HttpStack,
   SliceType,
 } from '../options.js'
+import { tusHttpStackNodeReadableBodyUnsupportedMessage } from '../protocol_generated.js'
 
 // TODO: Add tests for this.
 export class FetchHttpStack implements HttpStack {
@@ -51,9 +52,7 @@ class FetchRequest implements HttpRequest {
 
   async send(body?: SliceType): Promise<FetchResponse> {
     if (isNodeReadableStream(body)) {
-      throw new Error(
-        'Using a Node.js readable stream as HTTP request body is not supported using the Fetch API HTTP stack.',
-      )
+      throw new Error(tusHttpStackNodeReadableBodyUnsupportedMessage({ stackName: 'Fetch API' }))
     }
 
     const res = await fetch(this._url, {

lib/browser/XHRHttpStack.ts

@@ -6,6 +6,10 @@ import type {
   HttpStack,
   SliceType,
 } from '../options.js'
+import {
+  tusAbortErrorDescriptor,
+  tusHttpStackNodeReadableBodyUnsupportedMessage,
+} from '../protocol_generated.js'
 
 export class XHRHttpStack implements HttpStack {
   createRequest(method: string, url: string): HttpRequest {
@@ -68,7 +72,7 @@ class XHRRequest implements HttpRequest {
   send(body?: SliceType): Promise<HttpResponse> {
     if (isNodeReadableStream(body)) {
       throw new Error(
-        'Using a Node.js readable stream as HTTP request body is not supported using the XMLHttpRequest HTTP stack.',
+        tusHttpStackNodeReadableBodyUnsupportedMessage({ stackName: 'XMLHttpRequest' }),
       )
     }
 
@@ -82,7 +86,8 @@ class XHRRequest implements HttpRequest {
       }
 
       this._xhr.onabort = () => {
-        reject(new DOMException('Request was aborted', 'AbortError'))
+        const error = tusAbortErrorDescriptor()
+        reject(new DOMException(error.message, error.name))
       }
 
       this._xhr.send(body)

lib/browser/fileSignature.ts

@@ -1,42 +1,40 @@
-import type { ReactNativeFile, UploadInput, UploadOptions } from '../options.js'
+import type { UploadInput, UploadOptions } from '../options.js'
+import {
+  tusBrowserBlobFingerprint,
+  tusReactNativeFingerprint,
+  tusUnsupportedInputFingerprint,
+} from '../protocol_generated.js'
 import { isReactNativeFile, isReactNativePlatform } from '../reactnative/isReactNative.js'
 
 /**
  * Generate a fingerprint for a file which will be used the store the endpoint
  */
 export function fingerprint(file: UploadInput, options: UploadOptions) {
   if (isReactNativePlatform() && isReactNativeFile(file)) {
-    return Promise.resolve(reactNativeFingerprint(file, options))
+    return Promise.resolve(
+      tusReactNativeFingerprint({
+        endpoint: options.endpoint,
+        exifJson: file.exif ? JSON.stringify(file.exif) : null,
+        name: file.name,
+        size: file.size,
+      }),
+    )
   }
 
   if (file instanceof Blob) {
     return Promise.resolve(
-      //@ts-expect-error TODO: We have to check the input type here
-      // This can be fixed by moving the fingerprint function to the FileReader class
-      ['tus-br', file.name, file.type, file.size, file.lastModified, options.endpoint].join('-'),
+      tusBrowserBlobFingerprint({
+        endpoint: options.endpoint,
+        lastModified:
+          'lastModified' in file && typeof file.lastModified === 'number'
+            ? file.lastModified
+            : undefined,
+        name: 'name' in file && typeof file.name === 'string' ? file.name : undefined,
+        size: file.size,
+        type: file.type,
+      }),
     )
   }
 
-  return Promise.resolve(null)
-}
-
-function reactNativeFingerprint(file: ReactNativeFile, options: UploadOptions): string {
-  const exifHash = file.exif ? hashCode(JSON.stringify(file.exif)) : 'noexif'
-  return ['tus-rn', file.name || 'noname', file.size || 'nosize', exifHash, options.endpoint].join(
-    '/',
-  )
-}
-
-function hashCode(str: string): number {
-  // from https://stackoverflow.com/a/8831937/151666
-  let hash = 0
-  if (str.length === 0) {
-    return hash
-  }
-  for (let i = 0; i < str.length; i++) {
-    const char = str.charCodeAt(i)
-    hash = (hash << 5) - hash + char
-    hash &= hash // Convert to 32bit integer
-  }
-  return hash
+  return Promise.resolve(tusUnsupportedInputFingerprint())
 }