Uploads: binary-safe multipart uploads for small files, resumable uploads (chunked, with status query and resume) for large ones, and content replacement for existing files. upload-file and update-file-content switch to resumable automatically above 5 MiB.

Content may be Bytes (sent verbatim), a Str (its UTF-8 bytes), or a Map/Vec (sent as JSON). Bodies are assembled as Bytes, so binary data (0x00, 0xFF, invalid UTF-8) arrives intact.

Resumable uploads. A session is opened with start-resumable-upload, then content is PUT in chunks that are multiples of 256 KiB (default 8 MiB, opts.chunk-size). After each chunk, Drive's 308 Resume Incomplete says how much it has stored (its Range header), and the next chunk starts from there. When a chunk fails with 429/5xx or a dropped connection, the upload asks Drive for the stored offset (upload-status) and carries on from it, once, at once (google-core never waits; use a run retry policy for backoff). Sessions stay valid for a week; resume-upload continues an interrupted one, in this run or a later one.

A session URI is sent the call's credentials, so it must be a Google URL (or under google.drive.api-root) unless opts has its own credential: context credentials never go to another host.

Scopes. drive by default; drive.file is enough to create files and to update files the app created.

Values

CHUNK_ALIGN

CHUNK_ALIGN: Int 262144

CONVERT_TARGETS

CONVERT_TARGETS: Map {
  document: "application/vnd.google-apps.document",
  doc: "application/vnd.google-apps.document",
  spreadsheet: "application/vnd.google-apps.spreadsheet",
  sheet: "application/vnd.google-apps.spreadsheet",
  presentation: "application/vnd.google-apps.presentation",
  slides: "application/vnd.google-apps.presentation"
}

DEFAULT_CHUNK_SIZE

DEFAULT_CHUNK_SIZE: Int 8388608

GOOGLE_SESSION_URI_PATTERN

GOOGLE_SESSION_URI_PATTERN: Str "^https://[A-Za-z0-9.-]+\\.googleapis\\.com/"

RESUMABLE_THRESHOLD

RESUMABLE_THRESHOLD: Int 5242880

UPLOAD_LOCAL_KEYS

UPLOAD_LOCAL_KEYS: Vec [
  "parent",
  "parents",
  "description",
  "metadata",
  "resumable",
  "chunk-size",
  "convert-to",
  "file-id"
]

Functions

align-chunk-size

fn (size: Int): Int

Round a chunk size down to a multiple of 256 KiB (Drive's requirement for every chunk but the last), at least 256 KiB.

Example

::google::drive::upload/align-chunk-size(1000000)  // 786432
::google::drive::upload/align-chunk-size(1)  // 262144

build-multipart

fn (metadata: Map, content: Any, mime-type: Str, boundary: Str): Bytes

Build a multipart/related upload body as Bytes: a JSON metadata part (nulls dropped) and the content part, separated by boundary. Content is concatenated as bytes, never interpolated into a string, so binary payloads survive.

Example

body ::google::drive::upload/build-multipart({name: "a.txt"}, "hi", "text/plain", "b1")
contains(Str(body), "Content-Type: text/plain")  // true
ends-with(Str(body), "--b1--\r\n")  // true

chunk-bounds

fn (offset: Int, chunk-size: Int, total: Int): Vec

The [start, end) of the chunk beginning at offset (pure): end is offset + chunk-size, capped at total.

Example

::google::drive::upload/chunk-bounds(0, 8, 20)  // [0, 8]
::google::drive::upload/chunk-bounds(16, 8, 20)  // [16, 20]

classify-upload-response

fn (response: Result): Map

Interpret the response to a resumable-upload PUT (pure): returns {state: "complete", file}, {state: "incomplete", next-offset} (from the Range header of a 308), or {state: "retry", error} for failures worth another try (error is what to err if there are no tries left: an HttpError or a transport message), or an Err (expired session, other 4xx).

Example

::google::drive::upload/classify-upload-response({status: 308, headers: {range: "bytes=0-42"}})
// {state: "incomplete", next-offset: 43}

::google::drive::upload/classify-upload-response({status: 200, body: {id: "1AbC"}})
// {state: "complete", file: {id: "1AbC"}}

content-range

fn (start: Int, end: Int, total: Int): Str

The Content-Range for sending bytes start up to (not including) end of a total-byte upload: content-range(0, 524288, 2000000) is "bytes 0-524287/2000000". An empty range (start = end) is the status query form "bytes */<total>".

Example

::google::drive::upload/content-range(0, 524288, 2000000)  // "bytes 0-524287/2000000"
::google::drive::upload/content-range(2000000, 2000000, 2000000)  // "bytes */2000000"

convert-target

fn (value: Any): Str?

The Google-native MIME type to convert an upload into: "document"/"doc", "spreadsheet"/"sheet", "presentation"/"slides", or a full MIME type. Null means no conversion.

Example

::google::drive::upload/convert-target("sheet")  // "application/vnd.google-apps.spreadsheet"
::google::drive::upload/convert-target(null)  // null

new-boundary

fn (): Str

A random multipart boundary, so file content cannot collide with it.

Example

starts-with(::google::drive::upload/new-boundary(), "hot-drive-")  // true

next-offset-from-range

fn (range: Str?): Int

The next byte to send after a 308 Resume Incomplete, from its Range header: "bytes=0-42" means 43. No header means nothing was stored (0).

Example

::google::drive::upload/next-offset-from-range("bytes=0-42")  // 43
::google::drive::upload/next-offset-from-range(null)  // 0

resume-upload

fn (session-uri: Str, content: Any): Map
fn (session-uri: Str, content: Any, opts: Map): Map

Continue an interrupted resumable upload of content (the same bytes as before): ask Drive for the stored offset and send the rest. Returns the file resource, straight away if Drive already has every byte. An expired session (sessions last a week) is an Err: start a new upload.

bytes Bytes("report contents")
session ::google::drive::upload/start-resumable-upload({name: "big.bin"}, "application/octet-stream", length(bytes))
// ... store `session`; the upload is interrupted ...
file ::google::drive::upload/resume-upload(session, bytes)

session-uri-error

fn (session-uri: Str, opts: Map): Str?

Why session-uri may not be used with these opts, or null: it is a Google URL or under google.drive.api-root, or opts has its own credential. Context credentials are never sent to any other URL.

Example

::google::drive::upload/session-uri-error("https://www.googleapis.com/upload/drive/v3/files?upload_id=abc", {})  // null
is-some(::google::drive::upload/session-uri-error("https://example.com/session", {}))  // true

start-resumable-upload

fn (metadata: Map, mime-type: Str, size: Int): Str
fn (metadata: Map, mime-type: Str, size: Int, opts: Map): Str

POST (or PATCH, with opts.file-id) /upload/drive/v3/files?uploadType=resumable

  • open a resumable session for size bytes of mime-type with the given file metadata. Returns the session URI (from Location); store it to resume later.

Example

session ::google::drive::upload/start-resumable-upload({name: "video.mp4"}, "video/mp4", 52428800)

// A new version of an existing file
::google::drive::upload/start-resumable-upload({}, "video/mp4", 52428800, {file-id: "1AbCfile"})

to-bytes

fn (content: Any): Bytes

Upload content as Bytes: Bytes pass through, a Str becomes its UTF-8 bytes, null is empty, and anything else is JSON-encoded.

Example

length(::google::drive::upload/to-bytes("héllo"))  // 6
Str(::google::drive::upload/to-bytes({a: 1}))  // "{\"a\":1}"

update-file-content

fn (id: Str, content: Any, mime-type: Str): Map
fn (id: Str, content: Any, mime-type: Str, opts: Map): Map

PATCH /upload/files/{id} - replace a file's content (a new revision), optionally changing metadata via opts.metadata / description. Resumable above 5 MiB. Returns the file resource.

Example

file ::google::drive::upload/update-file-content("1AbCfile", "name,total\nAda,3\n", "text/csv")
file.version

// Also change the description
::google::drive::upload/update-file-content("1AbCfile", "{}", "application/json", {description: "Nightly export"})

upload-file

fn (name: Str, content: Any, mime-type: Str): Map
fn (name: Str, content: Any, mime-type: Str, parent: Str): Map
fn (name: Str, content: Any, mime-type: Str, opts: Map): Map

Create a file with content. A Str fourth argument is the parent folder id; an opts Map takes parent/parents, description, metadata (extra fields such as appProperties), convert-to ("document", "spreadsheet", "presentation": convert on upload, e.g. a .docx or .csv into a Google Doc/Sheet), resumable: true to force a resumable upload, chunk-size, Drive parameters (keepRevisionForever, ocrLanguage, useContentAsIndexableText, fields) and credentials. Returns the file resource.

folder-id "1AbCfolder"
csv-text "name,total\nAda,3\n"
file ::google::drive::upload/upload-file("report.csv", csv-text, "text/csv", folder-id)
sheet ::google::drive::upload/upload-file("report", csv-text, "text/csv", {parent: folder-id, convert-to: "spreadsheet"})

upload-resumable

fn (session-uri: Str, content: Any): Map
fn (session-uri: Str, content: Any, opts: Map): Map

Send content to an open session URI, starting at byte 0 (or opts.offset), in opts.chunk-size chunks (rounded down to 256 KiB multiples; default 8 MiB), following the offset Drive reports after each one. Returns the created/updated file resource.

Example

bytes Bytes("report contents")
session ::google::drive::upload/start-resumable-upload({name: "report.bin"}, "application/octet-stream", length(bytes))
file ::google::drive::upload/upload-resumable(session, bytes, {chunk-size: 524288})
file.id

upload-status

fn (session-uri: Str, total: Int): Map
fn (session-uri: Str, total: Int, opts: Map): Map

Ask Drive how much of a total-byte resumable upload it has stored (an empty PUT with Content-Range: bytes */total). Returns {complete, next-offset, file}: next-offset is the next byte to send (from the 308's Range header; 0 when nothing is stored), and file is the file resource once complete. An expired session or a failed query is an Err (::google::api/is-retryable says whether to try again later).

bytes Bytes("report contents")
session-uri ::google::drive::upload/start-resumable-upload({name: "report.bin"}, "application/octet-stream", length(bytes))
status ::google::drive::upload/upload-status(session-uri, length(bytes))
status.next-offset