filmopen_drive

A snapshot

This specification is a copy of docs/software/packages/filmopen_drive.md in the application’s repository, taken at commit 0b4fe88 of 11 November 2026. It is imported byte for byte and is not edited here; a change is made there, and arrives with the next snapshot.

Generated by scripts/package_digest.py; regenerate, never edit.

Google sign-in, the Drive HTTP client and a resumable target for sharing a film. The application’s root package does not import it — filmopen_sharing does — and Drive is never a media root. The package has no media store, source panel, folder-id preferences or cache.

Flutter. 10 files, 2,358 lines under lib/; 174 tests in 14 files. Barrel: lib/filmopen_drive.dart.

Depends on

• filmopen_format — uses ProjectArea, documentsFolder, isMediaFileName, mediaFolder, newUsageId, projectAreaOf, projectManifestFileName
• filmopen_media — uses StoreProblem
• filmopen_platform — uses CredentialStore, IncomingLinks
• filmopen_store — uses AppLog
• filmopen_sync — uses SyncBytes, SyncFailure, SyncReceipt, SyncTarget, SyncTargetException, TargetEntry, TargetInventory, ownedTransfer, transferChunks
• filmopen_jobs (dev) — uses nothing by name the digest could see

Third-party: url_launcher, http, crypto.

Used by

filmopen_sharing

Public API

What the barrel exports, file by file. A name is class, enum, mixin, extension, typedef, a top-level function, getter, setter or variable; under a class, its public constructors, fields, getters, setters and methods.

lib/src/drive_auth.dart

• class DriveAuth — The application’s way in and out of a Google account.
  • DriveAuth({ DriveTokenStore? tokens, DriveClientConfig? config, http.Client Function()? httpClient, DriveSignIn? signIn, DriveRefresh? refresh, thi…
  • static void withhold() — Withholds Google Drive from this process for good: an agent build’s entrypoint calls it before the app starts, so that no DriveAuth made afterwards reaches the platform’s credential store — the person’s tokens neith…
  • final DriveRedirects? redirects — The links the operating system hands the app, where the build has a door.
  • DriveClientConfig get config
  • bool get isConfigured — Whether this build could sign in at all.
  • Future<bool> get isSignedIn — Whether somebody has signed in on this machine.
  • Future<void> signIn({Future<void>? abandon}) — Opens the consent page and keeps its answer unless the caller abandons it.
  • Future<void> signOut() — Forgets the tokens.
  • Future<http.Client> client({bool refresh = false}) — An HTTP client with a live access token, refreshed when stale or when [refresh] is true.

lib/src/drive_client.dart — only DriveClient, DriveDownload, DriveError, DriveException, DriveFile, DriveTrail

• class DriveTrail — One sync operation’s trail through Drive: its id, and the area and project-relative path of the file it is about (§6.10).
  • DriveTrail([String? path]) — Starts a trail for the operation on [path], or on no one file.
  • final String opId — The id every line of this operation carries as op_id.
  • final String? area — The file’s area, data, media or root, or null for the whole folder.
  • final String? path — The file’s project-relative path, as it is.
  • http.Client? owner — The connection the operation owns: only its requests are logged as the operation’s, never another client’s, a caller’s callback running in the operation included.
  • String stage — Where the operation is, for its failure line: arguments, read (a put’s first source bytes) or drive.
  • int get ms — The milliseconds since the operation started.
  • static DriveTrail? get current — The trail of the operation the calling code runs in, or null outside one.
  • static DriveTrail? of(http.Client client) — The current trail where [client] is its operation’s own connection, else null.
  • Future<T> run<T>(Future<T> Function() body) — Runs [body] as this operation, so that every request it makes is logged under [opId].
  • void log(String event, Map<String, Object?> data) — Logs [event] with the operation’s id and [data].
• enum DriveError — Why a call to Drive did not do what was asked.
  • values: unconfigured, refused, notFound, alreadyThere, busy, full, unavailable
• class DriveException — What a Drive call refused to do, as a code.
  • const DriveException(this.code)
  • final DriveError code
• class DriveFile — One file or folder of a Drive, as much of it as FilmOpen uses.
  • const DriveFile({ required this.id, required this.name, this.isFolder = false, this.size, this.md5, })
  • final String id
  • final String name
  • final bool isFolder
  • final int? size — The bytes, where Drive reported them: a folder has none, and so does a file whose metadata was not asked for.
  • final String? md5 — The MD5 reported by Drive for these bytes.
  • static DriveFile? fromJson(Object? json)
• class DriveDownload — A ranged download’s actual starting byte and bounded response stream.
  • const DriveDownload({required this.from, required this.bytes}) — Keeps the actual start separate from the requested offset when Drive sends the whole file.
  • final int from — The first byte answered, zero for a full response or the verified Content-Range start.
  • final http.ByteStream bytes — The file bytes, bounded between chunks and cancelled by their consumer.
• class DriveClient — The calls, over whatever client the caller hands in.
  • DriveClient(this.client, { Uri? api, Uri? uploads, this.timeout = const Duration(seconds: 30), this.chunkTimeout = const Duration(minutes: 2), })
  • final http.Client client — A client that already carries the token, or a stand-in.
  • final Duration timeout — The bound for a metadata request and its response body.
  • final Duration chunkTimeout — The bound for sending one resumable chunk and reading its response.
  • void close() — Gives the connections back.
  • final Uri api — Where the calls go.
  • final Uri uploads — Where the bytes of an upload go, which is a host of its own.
  • Future<List<DriveFile>> childrenOf(String parentId, { bool foldersOnly = false, }) — The folders and files directly inside [parentId] (root for My Drive).
  • Future<DriveFile?> childNamed(String parentId, String name) — The one file of this name directly inside [parentId], or null.
  • Future<DriveFile?> fileById(String id) — One file or folder by its id, or null where there is no such thing any more, which is what a remembered id has to be asked, since listing the children of a folder that is gone answers an empty list rather than a refusal.
  • Future<DriveFile> createFolder({ required String parentId, required String name, })
  • Future<DriveFile> upload({ required String parentId, required String name, required List<int> bytes, String? mimeType, }) — Creates a file with one replayable multipart request.
  • Future<String> startResumableUpload({ required String parentId, required String name, required int length, String? mimeType, }) — Starts a session and returns only its opaque upload id, never its address.
  • Future<int> resumableCommitted(String uploadId, int length) — Asks a resumable session how many bytes it already holds.
  • Future<DriveFile?> sendChunk(String uploadId, { required int from, required int length, required List<int> bytes, }) — Sends one chunk, returning metadata only when the file is complete.
  • Future<DriveFile> replaceContent(String fileId, List<int> bytes, { String? mimeType, }) — Replaces a document’s bytes while keeping its existing Drive id.
  • Future<DriveDownload> download(String id, {int from = 0}) — Downloads a file from [from], accepting a full response from zero or a verified range at that offset.

lib/src/drive_config.dart

• variable const String kDriveScope — The one scope FilmOpen asks for.
• class DriveClientConfig — The OAuth client of a build.
  • const DriveClientConfig({required this.id, required this.secret, this.androidId = ''})
  • final String id — The client id of a Desktop app client of the owner’s Google Cloud project, or empty in a build that has none.
  • final String secret — The desktop client’s secret, which Google does not treat as one.
  • final String androidId — The client id of an Android client of the same project, or empty in a build that has none.
  • String clientIdFor(TargetPlatform platform) — The client id a build on [platform] signs in with.
  • String? clientSecretFor(TargetPlatform platform) — What a build on [platform] may send as the client’s secret.
  • bool isConfiguredFor(TargetPlatform platform) — Whether a build on [platform] has the client it needs.
  • bool get isConfigured — Whether this build has the client its platform needs.
  • static const DriveClientConfig current — From the build, never from this file. The client of this build, from the keys the build was made with (--dart-define-from-file).

lib/src/drive_consent.dart

• variable final Uri kGoogleAuthorizationEndpoint — Google’s own consent endpoint for an installed application.
• function Uri driveConsentUri({ required String clientId, required String redirectUri, required String scope, required String codeVerifier, required String s… — The address to open in the person’s own browser.
• function String androidRedirectUri(String clientId) — Google’s redirect for an Android OAuth client: the client id reversed, as a scheme of its own, with a path Google’s own examples use.
• function String androidRedirectScheme(String clientId) — The scheme alone, which is what the manifest declares.
• function Future<String> codeFromDriveRedirect(Stream<Uri> links, { required String scheme, required String state, Duration within = const Duration(minutes:… — The code in the first redirect of ours to arrive on [links], within [within].
• function String codeChallengeFor(String verifier) — The S256 challenge of a verifier: base64url of its SHA-256, without padding (RFC 7636 §4.2).
• function String newCodeVerifier() — 128 unreserved characters from a secure source (RFC 7636 §4.1).
• function String newState() — What ties the answer to this request, so that a reply for somebody else’s is refused.

lib/src/drive_sync_target.dart

• class DriveSyncTarget — A film’s folder in My Drive as a sync target (§6.10): the manifest at the folder’s top, the documents in data and the media in media.
  • DriveSyncTarget({ required DriveAuth auth, required String folderId, DriveClient Function(http.Client)? clientFor, int resumableFrom = 5 << 20, int… — A target for the film’s Drive folder [folderId], sending and receiving as [auth].
  • static void forgetLookups(DriveAuth auth) — Forgets the folders’ lookups held for [auth], so each film’s next operation asks for its folder afresh.

lib/src/drive_tokens.dart

• class DriveTokens — What a sign-in leaves behind.
  • const DriveTokens({required this.accessToken, required this.expiresAt, required this.refreshToken})
  • final String accessToken
  • final DateTime expiresAt — In UTC, as Google gives it.
  • final String? refreshToken — Null where Google gave none back — a second consent in the same hour, for one — in which case the stored one is kept.
  • bool get isFresh — A minute’s grace, so a token that is about to expire is refreshed before a large upload rather than in the middle of one.
  • Map<String, Object?> toJson()
  • static DriveTokens? fromJson(Object? json)
• class DriveTokenStore — Where the tokens are kept.
  • Future<DriveTokens?> read()
  • Future<void> write(DriveTokens tokens)
  • Future<void> clear()
• class SecureDriveTokenStore — The platform’s own credential store, through the one door, CredentialStore.current, and its guard (§6.7).
  • const SecureDriveTokenStore([this._store])
  • CredentialStore get storage — The store the tokens are read from and written to: the one given, else the app’s door at the time of the call.
• typedef typedef DriveSignIn — Opening the consent page and coming back with tokens.
• typedef typedef DriveRedirects — The links the operating system hands the app, as the consent flow needs them.
• typedef typedef DriveRefresh — Asking Google for a fresh access token with a refresh token.
• function Future<DriveTokens> exchangeCodeWithGoogle(DriveClientConfig config, String code, { required String verifier, required String redirectUri, required… — The code exchange, which FilmOpen writes itself on every platform.
• variable const String kGoogleTokenEndpoint — Google’s token endpoint, which both the exchange and the refresh post to.
• function Future<DriveTokens> refreshThroughGoogle(DriveClientConfig config, String refreshToken, http.Client client, { TargetPlatform? platform, }) — The refresh call, which is plain HTTP on every platform.

Internal

Files under lib/ the barrel does not reach; nothing outside the package may import them.

• lib/src/drive_sign_in.dart
• lib/src/drive_sign_in_io.dart: kDriveConsentTimeout, signInThroughBrowser, _openInTheBrowser, _throughTheLoopback, _throughTheLinkDoor, _consentThen, _codeFromRedirect
• lib/src/drive_sign_in_stub.dart: kDriveConsentTimeout, signInThroughBrowser