Skip to content
← Public packages

@kody/dropbox

Reusable Dropbox OAuth helpers for account, metadata, search, file transfer, sharing, and generic API requests.

FollowFork

Files

upload-session.ts

340 lines · 12.1 KB · TypeScript
/**
 * Low-level Dropbox upload-session helpers (start, append, finish, get-offset)
 * for uploads that arrive in pieces across several execute calls or a long
 * local run. Each piece goes straight to Dropbox as raw bytes, so a caller can
 * resume from any offset. Use the box script `scripts/upload-to-dropbox.mjs`
 * for a whole local file; use these helpers when you drive the session yourself.
 *
 * Writes require `confirm: true`; the entrypoint supports `dryRun: true`.
 *
 * @example
 * import {
 *   startUploadSession,
 *   appendUploadSession,
 *   finishUploadSession,
 * } from 'kody:@kody/dropbox/upload-session'
 * const { sessionId } = await startUploadSession({ confirm: true })
 * const { offset } = await appendUploadSession({ sessionId, offset: 0, bytes, confirm: true })
 * const metadata = await finishUploadSession({
 *   sessionId,
 *   offset,
 *   commit: { path: '/Apps/Kody/inbox/file.bin', mode: 'add' },
 *   confirm: true,
 * })
 */

import { createAuthenticatedFetch, credential } from 'kody:runtime'
import { decodeBase64 } from './base64.ts'
import { DROPBOX_CONTENT_ORIGIN, DropboxApiError } from './request.ts'
import type { JsonRecord } from './types.ts'
import {
	optionalBoolean,
	optionalNumber,
	requireDropboxPath,
	requireRecord,
	requireString,
} from './types.ts'

/** Recommended bytes per append for local execute (16 MiB, a multiple of 4 MiB). */
export const UPLOAD_SESSION_RECOMMENDED_CHUNK_BYTES = 16 * 1024 * 1024

/** Kody gateway ceiling (Dropbox itself allows 150 MiB). */
export const UPLOAD_SESSION_MAX_CHUNK_BYTES = 100 * 1024 * 1024

export type UploadSessionCommit = {
	path: string
	mode?: 'add' | 'overwrite'
	autorename?: boolean
	mute?: boolean
	strictConflict?: boolean
}

export type UploadSessionCursor = { sessionId: string; offset: number }

type BytesInput = { bytes?: Uint8Array; bytesBase64?: string }

let contentFetch: typeof fetch | null = null

async function getContentFetch(): Promise<typeof fetch> {
	if (contentFetch) return contentFetch
	try {
		const client = await credential('dropbox')
		if (client && typeof client.fetch === 'function') {
			contentFetch = client.fetch as typeof fetch
			return contentFetch
		}
	} catch {
		// Fall back to the integration fetch used by the rest of this package.
	}
	contentFetch = await createAuthenticatedFetch('dropbox')
	return contentFetch
}

/** JSON for the Dropbox-API-Arg header, with non-ASCII escaped as Dropbox requires. */
export function encodeApiArg(apiArg: unknown): string {
	return JSON.stringify(apiArg).replace(
		/[\u007f-\uffff]/g,
		(char) => `\\u${char.charCodeAt(0).toString(16).padStart(4, '0')}`,
	)
}

async function postContent(endpoint: string, apiArg: JsonRecord, bytes: Uint8Array) {
	if (bytes.byteLength > UPLOAD_SESSION_MAX_CHUNK_BYTES) throw new Error('Upload body exceeds 100 MiB Kody gateway limit')
	const authedFetch = await getContentFetch()
	const response = await authedFetch(`${DROPBOX_CONTENT_ORIGIN}/2/${endpoint}`, {
		method: 'POST',
		headers: {
			accept: 'application/json',
			'content-type': 'application/octet-stream',
			'dropbox-api-arg': encodeApiArg(apiArg),
		},
		body: bytes as BodyInit,
	})
	const text = await response.text()
	let body: unknown = null
	if (text) {
		try {
			body = JSON.parse(text)
		} catch {
			body = text
		}
	}
	if (!response.ok) {
		throw new DropboxApiError(
			`Dropbox API request failed: ${response.status} ${response.statusText} (${endpoint})`,
			{
				status: response.status,
				statusText: response.statusText,
				requestId: response.headers.get('x-dropbox-request-id'),
				details: body,
				retryAfterMs: response.headers.has('retry-after') ? Math.max(0, /^\d+(\.\d+)?$/.test(response.headers.get('retry-after')!) ? Number(response.headers.get('retry-after')) * 1000 : Date.parse(response.headers.get('retry-after')!) - Date.now()) : undefined,
			},
		)
	}
	return body
}

function resolveBytes(input: BytesInput, label: string): Uint8Array {
	if (input.bytes instanceof Uint8Array) return input.bytes
	if (input.bytes !== undefined) throw new Error(`${label}: bytes must be a Uint8Array.`)
	if (typeof input.bytesBase64 === 'string') return decodeBase64(input.bytesBase64)
	return new Uint8Array(0)
}

function requireConfirm(confirm: unknown, action: string) {
	if (confirm !== true) {
		throw new Error(
			`upload-session ${action} writes to Dropbox. Pass confirm: true only after explicit user approval, or use dryRun: true.`,
		)
	}
}

function requireOffset(value: unknown): number {
	const offset = optionalNumber(value, 'offset') ?? 0
	if (!Number.isInteger(offset) || offset < 0) throw new Error('offset must be a non-negative integer.')
	return offset
}

function requireSessionId(value: unknown): string {
	return requireString(value, 'sessionId')
}

/**
 * Read the correct offset from a Dropbox `incorrect_offset` error (409), for
 * append (`error.correct_offset`) and finish (`error.lookup_failed.correct_offset`).
 * Returns `null` when the error is something else.
 */
export function getCorrectOffsetFromError(error: unknown): number | null {
	if (!(error instanceof DropboxApiError) && !(error && typeof error === 'object' && 'details' in error)) {
		return null
	}
	const details = (error as { details?: unknown }).details
	const visit = (value: unknown, depth: number): number | null => {
		if (!value || typeof value !== 'object' || depth > 4) return null
		const record = value as JsonRecord
		if (record['.tag'] === 'incorrect_offset' && typeof record.correct_offset === 'number') {
			return record.correct_offset
		}
		for (const key of ['error', 'lookup_failed']) {
			const found = visit(record[key], depth + 1)
			if (found !== null) return found
		}
		return null
	}
	return visit(details, 0)
}

/**
 * Start an upload session, optionally with the first bytes.
 * @returns `{ sessionId, offset }` where `offset` is the number of bytes sent.
 */
export async function startUploadSession(
	input: BytesInput & { close?: boolean; confirm?: boolean } = {},
): Promise<UploadSessionCursor> {
	requireConfirm(input.confirm, 'start')
	const bytes = resolveBytes(input, 'start')
	const close = optionalBoolean(input.close, 'close') ?? false
	const body = (await postContent('files/upload_session/start', { close }, bytes)) as JsonRecord
	const sessionId = typeof body?.session_id === 'string' ? body.session_id : ''
	if (!sessionId) throw new Error('upload_session/start did not return session_id.')
	return { sessionId, offset: bytes.byteLength }
}

/**
 * Append bytes at `offset`. Throws `DropboxApiError` (409) on a wrong offset;
 * read the right one with `getCorrectOffsetFromError(error)` or `getUploadSessionOffset`.
 * @returns `{ sessionId, offset }` with the next offset to write.
 */
export async function appendUploadSession(
	input: BytesInput & { sessionId: string; offset: number; close?: boolean; confirm?: boolean },
): Promise<UploadSessionCursor> {
	requireConfirm(input.confirm, 'append')
	const sessionId = requireSessionId(input.sessionId)
	let offset = requireOffset(input.offset)
	const bytes = resolveBytes(input, 'append')
	const close = optionalBoolean(input.close, 'close') ?? false
	await postContent('files/upload_session/append_v2', { cursor: { session_id: sessionId, offset }, close }, bytes)
	offset += bytes.byteLength
	return { sessionId, offset }
}

/**
 * Ask Dropbox how many bytes the session holds. Sends an empty append at the
 * guessed offset (default 0): success means the guess is right, a 409
 * `incorrect_offset` carries the right value. Never changes stored bytes.
 */
export async function getUploadSessionOffset(input: {
	sessionId: string
	offset?: number
}): Promise<UploadSessionCursor> {
	const sessionId = requireSessionId(input.sessionId)
	const guess = requireOffset(input.offset ?? 0)
	try {
		await postContent(
			'files/upload_session/append_v2',
			{ cursor: { session_id: sessionId, offset: guess }, close: false },
			new Uint8Array(0),
		)
		return { sessionId, offset: guess }
	} catch (error) {
		const correct = getCorrectOffsetFromError(error)
		if (correct === null) throw error
		return { sessionId, offset: correct }
	}
}

function buildCommit(commit: UploadSessionCommit): JsonRecord {
	const record = requireRecord(commit, 'commit')
	const path = requireDropboxPath(record.path, 'commit.path')
	const mode = record.mode ?? 'add'
	if (mode !== 'add' && mode !== 'overwrite') throw new Error('commit.mode must be "add" or "overwrite".')
	return {
		path,
		mode,
		autorename: optionalBoolean(record.autorename, 'commit.autorename') ?? false,
		mute: optionalBoolean(record.mute, 'commit.mute') ?? false,
		strict_conflict: optionalBoolean(record.strictConflict, 'commit.strictConflict') ?? false,
	}
}

/**
 * Finish the session with optional last bytes and commit it to `commit.path`.
 * `offset` is the total bytes already appended (before these last bytes).
 * @returns Dropbox file metadata (`size`, `content_hash`, `path_display`, `rev`, ...).
 */
export async function finishUploadSession(
	input: BytesInput & {
		sessionId: string
		offset: number
		commit: UploadSessionCommit
		confirm?: boolean
	},
): Promise<JsonRecord> {
	requireConfirm(input.confirm, 'finish')
	const sessionId = requireSessionId(input.sessionId)
	const offset = requireOffset(input.offset)
	const commit = buildCommit(input.commit)
	const bytes = resolveBytes(input, 'finish')

	const body = await postContent(
		'files/upload_session/finish',
		{ cursor: { session_id: sessionId, offset }, commit },
		bytes,
	)
	return requireRecord(body, 'upload_session/finish response')
}

type UploadSessionAction = 'start' | 'append' | 'finish' | 'get-offset'

/**
 * Drive one upload-session step per call (handy from hosted execute, where a
 * request body is capped near 4 MB, so keep each `bytesBase64` under ~2.5 MiB).
 *
 * @param params.action - `start`, `append`, `finish`, or `get-offset`.
 * @param params.sessionId - Session id from `start` (append, finish, get-offset).
 * @param params.offset - Bytes already in the session (append, finish; a guess for get-offset).
 * @param params.bytesBase64 - Bytes for this step, in params (never in code).
 * @param params.commit - `{ path, mode?, autorename?, mute? }` for finish.
 * @param params.confirm - Required `true` for start, append, and finish.
 * @param params.dryRun - Return the planned step without calling Dropbox.
 * @returns start/append/get-offset: `{ sessionId, offset }` (next offset); finish: file metadata.
 *
 * @example
 * import uploadSession from 'kody:@kody/dropbox/upload-session'
 * const next = await uploadSession({
 *   action: 'append',
 *   sessionId: params.sessionId,
 *   offset: params.offset,
 *   bytesBase64: params.bytesBase64,
 *   confirm: true,
 * })
 */
export default async function uploadSessionEntrypoint(
	params: Record<string, unknown> = {},
) {
	const input = requireRecord(params, 'upload-session')
	const action = input.action as UploadSessionAction
	if (!['start', 'append', 'finish', 'get-offset'].includes(action)) {
		throw new Error('action must be "start", "append", "finish", or "get-offset".')
	}
	const bytesBase64 =
		input.bytesBase64 === undefined
			? undefined
			: requireString(input.bytesBase64, 'bytesBase64', { allowEmpty: true })
	if (input.dryRun === true) {
		return {
			dryRun: true,
			action,
			sessionId: input.sessionId ?? null,
			offset: input.offset ?? null,
			byteLength: bytesBase64 === undefined ? 0 : decodeBase64(bytesBase64).byteLength,
			commit: action === 'finish' ? buildCommit(input.commit as UploadSessionCommit) : null,
			authorization: '[managed dropbox OAuth integration]',
		}
	}
	switch (action) {
		case 'start':
			return startUploadSession({ bytesBase64, close: input.close as boolean | undefined, confirm: input.confirm as boolean })
		case 'append':
			return appendUploadSession({
				sessionId: input.sessionId as string,
				offset: input.offset as number,
				bytesBase64,
				close: input.close as boolean | undefined,
				confirm: input.confirm as boolean,
			})
		case 'finish':
			return finishUploadSession({
				sessionId: input.sessionId as string,
				offset: input.offset as number,
				bytesBase64,
				commit: input.commit as UploadSessionCommit,
				confirm: input.confirm as boolean,
			})
		case 'get-offset':
			return getUploadSessionOffset({
				sessionId: input.sessionId as string,
				offset: input.offset as number | undefined,
			})
	}
}