Read file content: read-document for any file (Paper docs and other
export-only files are exported, everything else downloaded),
byte-exact downloads, Range and chunked downloads past the response
cap, exports, temporary links, and Dropbox's content_hash.
Results are ::dropbox/FileContent: bytes is always the raw body
(the response's body-bytes), and text is filled in when the MIME
type (from the file name; Dropbox sends no useful Content-Type) is
textual. The file's metadata comes from the Dropbox-API-Result
header and is attached as a DocFile.
Limits. Every single response is capped by the runtime's
http.max-response-bytes (16 MiB by default, 120 s timeout):
download switches to Range-chunked downloads (pinned to the file's
rev) when a file is larger. Exports cannot be ranged. The whole
file is held in memory either way.
Scopes. files.content.read.
Values
BLOCK_SIZE
BLOCK_SIZE: Int 4194304
DEFAULT_DOWNLOAD_CHUNK
DEFAULT_DOWNLOAD_CHUNK: Int 8388608
DOWNLOAD_LOCAL_KEYS
DOWNLOAD_LOCAL_KEYS: Vec [
"range",
"chunk-size"
]
FORMAT_ALIASES
FORMAT_ALIASES: Map {
md: "markdown",
markdown: "markdown",
htm: "html",
html: "html",
txt: "plain_text",
text: "plain_text",
plain: "plain_text",
plain_text: "plain_text"
}
FORMAT_MIMES
FORMAT_MIMES: Map {
markdown: "text/markdown",
html: "text/html",
plain_text: "text/plain",
pdf: "application/pdf",
docx: "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
xlsx: "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
pptx: "application/vnd.openxmlformats-officedocument.presentationml.presentation",
csv: "text/csv"
}
Functions
build-content
fn (file-id: Str, bytes: Bytes, entry: Map?, name: Str?, format: Str?, source: Str): ::dropbox/FileContent
Build a FileContent (pure) from bytes, the file's metadata entry
(null when unknown), the output name (the export name for exports)
and the export format (null for downloads). The MIME type comes
from name, else from format.
content-hash
fn (content: Bytes | Str): Str
fn (content: Bytes | Str, block-size: Int): Str
Dropbox's content_hash of some content (pure): split it into 4 MiB
blocks, SHA-256 each block, concatenate the raw digests, and SHA-256
that, as lowercase hex. An empty file hashes the empty string. Use it
to skip downloads of unchanged files (compare with a metadata entry's
content_hash) or to check a download. The 2-arity form takes
another block size (for tests).
See https://www.dropbox.com/developers/reference/content-hash.
::dropbox::content/content-hash(Bytes("hello"))
// "9595c9df90075148eb06860365df33584b75bff782a510c6cd4883a419833d50"
download
fn (path: Str): ::dropbox/FileContent
fn (path: Str, opts: Map): ::dropbox/FileContent
POST files/download (content host) - a file's exact bytes as a
FileContent, with its metadata from Dropbox-API-Result. Files
larger than http.max-response-bytes are fetched again in Range
chunks (download-chunked). Export-only files (Paper docs) fail with
409 unsupported_file: use read-document or export.
Options: rev (a specific revision), range: {start, end}
(inclusive; end null for the rest) for a partial download,
chunk-size for the chunked fallback, plus credentials.
pdf ::dropbox::content/download("/Reports/Q3.pdf")
pdf.mime-type // "application/pdf"
pdf.bytes // exact bytes
pdf.file.rev
download-arg
fn (path: Str, opts: Map): Map
The files/download argument (pure): path, or rev:<rev> when opts.rev is set (Dropbox deprecated the separate rev field in favour of a rev: path), plus other Dropbox arguments from opts.
download-chunked
fn (path: Str): ::dropbox/FileContent
fn (path: Str, opts: Map): ::dropbox/FileContent
Download a file in Range requests of opts.chunk-size bytes (default
8 MiB; keep it under http.max-response-bytes) and join them, so
files larger than one response can be read. Every chunk asks for the
rev the metadata reported, so a file changing mid-download cannot
mix versions. The whole file is still held in memory.
download-range
fn (path: Str, start: Int, end: Int): ::dropbox/FileContent
fn (path: Str, start: Int, end: Int, opts: Map): ::dropbox/FileContent
Download bytes start..end (inclusive) of a file.
download-ranges
fn (size: Int, chunk-size: Int): Vec
Split size bytes into inclusive [start, end] ranges of at most chunk-size bytes (pure). download-ranges(10, 4) is [[0, 3], [4, 7], [8, 9]].
download-text
fn (path: Str): Str
fn (path: Str, opts: Map): Str
Download a file and decode it as UTF-8 text.
export
fn (path: Str): ::dropbox/FileContent
fn (path: Str, format: Str?): ::dropbox/FileContent
fn (path: Str, format: Str?, opts: Map): ::dropbox/FileContent
POST files/export (content host) - export a file that cannot be
downloaded directly (Paper docs, cloud docs) as a FileContent.
format is checked by export-format when opts.entry (the file's
metadata) is given; null uses the file's default (export_as).
Dropbox answers 409 retry_error while an export is not ready yet
(is-retryable is true for it).
md ::dropbox::content/export("/Notes/Roadmap.paper", "markdown")
md.text
export-format
fn (entry: Map?, format: Str?): Str?
Pick the export format for an export-only file (pure). entry is its
metadata (null when unknown); format is a Dropbox format name or an
alias (md/markdown, html, text/txt for plain_text), or
"auto"/null. "auto" prefers markdown when the file offers it,
else the file's default export_as. When the entry lists
export_options, a format outside them is an Err naming the options.
Returns null to let Dropbox use the default.
::dropbox::content/export-format({export_info: {export_as: "html", export_options: ["html", "markdown"]}}, "auto")
// "markdown"
fetch-ranges
fn (arg: Map, ranges: Vec, index: Int, acc: Bytes, opts: Map): Bytes
get-temporary-link
fn (path: Str): Map
fn (path: Str, opts: Map): Map
POST files/get_temporary_link - a direct download link for a file, valid for four hours: {metadata, link}. Anyone with the link can download the file, so treat it as a secret. Not available for export-only files.
hash-loop
fn (data: Bytes, block-size: Int, offset: Int, acc: Bytes): Bytes
is-size-limit-error
fn (result: Result): Bool
True when a request failed because the response exceeded http.max-response-bytes.
matches-content-hash
fn (content: Bytes | Str, expected: Str?): Bool
True when content hashes to expected (a metadata entry's content_hash). False for a null or empty expected.
range-header
fn (start: Int, end: Int?): Str
An HTTP Range value for bytes start..end inclusive (end null for "to the end"): range-header(0, 1023) is "bytes=0-1023".
read-document
fn (path: Str): ::dropbox/FileContent
fn (path: Str, format: Str?): ::dropbox/FileContent
fn (path: Str, format: Str?, opts: Map): ::dropbox/FileContent
Read any file as a FileContent with its DocFile attached.
- Paper docs and other export-only files are exported in
format("auto"by default: Markdown when offered, else the file's default export); seeexport-formatfor the names. - Other files are downloaded as stored (
formatis ignored):textis set for textual types (.txt,.md,.csv,.json, ...) andbytesalways holds the exact content. - Folders and deleted entries return an Err.
doc ::dropbox::content/read-document("/Notes/Roadmap.paper", "markdown")
doc.text // Markdown, ready for chunking and embedding
doc.file.version // the rev, for incremental re-indexing
read-document-text
fn (path: Str): Str
fn (path: Str, format: Str?): Str
fn (path: Str, format: Str?, opts: Map): Str
read-document, returning just the text; an Err when the result is not textual (a PDF, an image, ...).
response-bytes
fn (response: Map): Bytes
The exact body of a response as Bytes: body-bytes (never the auto-decoded body), else a Str body's UTF-8 bytes, else empty.