filen_client library
FilenClient: Facade that composes all modules into a single API surface.
This is also the barrel file — import this to get access to all modules.
Classes
- CacheEntry
- ChunkSemaphore
- A counting semaphore that bounds the number of concurrent in-flight chunk transfers. Paired with MemoryGate (which bounds the bytes in flight), it caps chunk concurrency by both count and memory — the Step 1 model.
- ConfigService
- ConfigStorage
- DigestSink
- Helper class to capture hash results from chunked hash computation.
- FileConfigStorage
- File-based credential storage (default for CLI usage).
- FilenApi
- FilenAuth
- FilenCache
- FilenClient
- FilenCrypto
- FilenDownload
- FilenDrive
- FilenUpload
- InMemoryConfigStorage
- In-memory credential storage for unit tests.
- MemoryGate
Extensions
Constants
- credentialsFmt → const String
- credentialsKeyEnv → const String
- kDefaultDownloadConcurrency → const int
- Chunk download concurrency (Step 1). N chunks fetched + decrypted at once, bounded by a ChunkSemaphore; out-of-order completion is reassembled by writing each chunk at its fixed file offset.
- kDefaultFileConcurrency → const int
- File-level (batch) concurrency (Step 2). W = whole FILES transferred at once in a batch directory upload/download — the bigger real-world win when syncing many files. Each file ALSO runs Step 1 chunk concurrency internally, so the dangerous quantity is the PRODUCT (W files × N chunks each). One shared ChunkSemaphore caps that product across the whole batch: every chunk transfer (sequential OR concurrent path) takes one permit before the network call and releases it after, so total in-flight is bounded regardless of how W and the per-file degree combine. (The per-chunk MemoryGate still bounds bytes; this bounds the cross-file count.)
- kDefaultUploadConcurrency → const int
- Chunk transfer concurrency (Step 1). N chunks may be in flight at once, bounded by both a ChunkSemaphore (count) and the MemoryGate (bytes), so at most N×(plaintext + encrypted) chunks are ever live — important on mobile.
- kGlobalMaxInflightChunks → const int
- Total chunks allowed in flight across ALL files × their chunks. At ~2 MB live per chunk this is a ~16 MB ceiling — matters on mobile (CrispCloud).
- kSequentialChunkThreshold → const int
- Files with this many chunks or fewer keep the simple sequential path — no concurrency machinery is spun up (the overlap win doesn't pay for tiny files).
- kSequentialDownloadChunkThreshold → const int
- Files with this many chunks or fewer keep the simple sequential path.
Functions
-
contiguousCompletedMax(
Set< int> completed) → int -
Largest M such that chunks 0..M are all in
completed(else -1). Expresses an out-of-order completed set as a backward-compatible high-water mark. -
formatDate(
dynamic dateValue) → String - Format a date value (int timestamp or string) into YYYY-MM-DD.
-
formatSize(
dynamic b) → String - Format a byte count into a human-readable string (e.g., "1.5 MB").
-
runWithConcurrency<
T> (Iterable< T> items, int concurrency, Future<void> action(T item)) → Future<void> -
Run
actionoveritemswith at mostconcurrencyin flight at once. Mirrors internxt-dart's runWithConcurrency: a ChunkSemaphore gates how many item futures are active; the rest queue. This is the file-level (Step 2) batch primitive — each whole-file transfer is one item, and the per-file chunk concurrency (Step 1) composes underneath. Completes once every item has finished. Ifactionthrows for an item, that error propagates out of the returned future (callers that must not abort the batch should catch insideactionand return a sentinel instead). -
shouldIncludeFile(
String fileName, List< String> include, List<String> exclude) → bool - Check if a filename should be included based on include/exclude glob patterns.
Exceptions / Errors
- ChunkUploadException
- Exception for chunk upload failures (carries resume state).