fluppy library

Fluppy - A modular, headless file upload library for Dart

Inspired by Uppy, Fluppy provides a flexible, event-driven API for uploading files to S3 and S3-compatible storage services.

Features

S3 Uploads: Direct uploads to S3 with presigned URLs
Multipart Support: Automatic chunking for large files
Pause/Resume: Full control over upload lifecycle
Progress Tracking: Real-time upload progress events
Retry Logic: Automatic retry with exponential backoff
Headless: Bring your own UI (works with Flutter, CLI, server)

Quick Start

import 'package:fluppy/fluppy.dart';

final fluppy = Fluppy(
  uploader: S3Uploader(
    options: S3UploaderOptions(
      getUploadParameters: (file, options) async {
        // Get presigned URL from your backend
        final response = await myBackend.getPresignedUrl(file.name);
        return UploadParameters(
          method: 'PUT',
          url: response.url,
          headers: {'Content-Type': file.type ?? 'application/octet-stream'},
        );
      },
      // ... other callbacks for multipart uploads
    ),
  ),
);

// Add files
fluppy.addFile(FluppyFile.fromPath('/path/to/file.mp4'));

// Listen to events
fluppy.events.listen((event) {
  switch (event) {
    case UploadProgress(:final progress):
      print('Progress: ${progress.percent}%');
    case UploadComplete(:final response):
      print('Complete: ${response?.location}');
    default:
      break;
  }
});

// Upload
await fluppy.upload();

See the example for a complete working example with multipart uploads.

Classes

AbortMultipartOptions: Options for aborting a multipart upload.
AllUploadsComplete: Emitted when all uploads in the queue are complete.
AwsSignatureV4: AWS Signature Version 4 implementation for creating presigned URLs.
CancellationToken: A simple cancellation token for aborting async operations.
CompleteMultipartOptions: Options for completing a multipart upload.
CompleteMultipartResult: Result from completing a multipart upload.
CreateMultipartUploadResult: Result from initiating a multipart upload.
CredentialsOptions: Options for getting temporary security credentials.
FileAdded: Emitted when a file is added to the upload queue.
FileRemoved: Emitted when a file is removed from the queue.
Fluppy: The main Fluppy class that orchestrates file uploads.
FluppyEvent: Base class for all Fluppy events.
FluppyFile: Represents a file to be uploaded.
ListPartsOptions: Options for listing parts of a multipart upload.
MetadataUtils: Utility for filtering metadata fields.
RetryConfig: Options for retry behavior.
S3MultipartState
S3Part: Represents a single part in an S3 multipart upload.
S3PartUploaded: Emitted when an S3 multipart upload part is completed.
S3Uploader: S3 Uploader implementation supporting both single-part and multipart uploads.
S3UploaderOptions: Configuration options for S3 uploads.
S3Utils: Helper utilities for S3 URL handling.
SignPartOptions: Options for signing a single part.
SignPartResult: Result from signing a part.
StateChanged: Emitted when upload state changes (useful for UI updates).
TemporaryCredentials: Temporary AWS credentials for direct uploads.
UploadCancelled: Emitted when an upload is cancelled.
UploadComplete: Emitted when an upload completes successfully.
Uploader: Abstract base class for upload implementations.
UploadError: Emitted when an upload fails with an error.
UploadOptions: Options passed to S3UploaderOptions.getUploadParameters.
UploadParameters: Parameters for single-part (non-multipart) uploads.
UploadPartBytesOptions: Options for uploading part bytes.
UploadPartBytesResult: Result from uploading part bytes.
UploadPaused: Emitted when an upload is paused.
UploadProgress: Emitted periodically during upload with progress information.
UploadProgressInfo: Upload progress information.
UploadResponse: Response from a completed upload.
UploadResumed: Emitted when a paused upload is resumed.
UploadRetry: Emitted when a retry is attempted.
UploadStarted: Emitted when an upload starts.

Enums

FileSourceType: The source type of a file.
FileStatus: The status of a file in the upload queue.

Mixins

RetryMixin

Extensions

S3FilePublic on FluppyFile: Public S3 extension for FluppyFile.
TemporaryCredentialsSigningExtension on TemporaryCredentials: Extension to create signed URLs from TemporaryCredentials.

Constants

defaultChunkSize → const int: Default chunk size (5 MiB - S3 minimum).
defaultMultipartThreshold → const int: Default multipart threshold (100 MiB).
maxParts → const int: Maximum number of parts (S3 limit).
minChunkSize → const int: Minimum chunk size (5 MiB - S3 requirement).

Typedefs

AbortMultipartUploadCallback = Future<void> Function(FluppyFile file, AbortMultipartOptions options): Signature for the abortMultipartUpload callback.
CompleteMultipartUploadCallback = Future<CompleteMultipartResult> Function(FluppyFile file, CompleteMultipartOptions options): Signature for the completeMultipartUpload callback.
CreateMultipartUploadCallback = Future<CreateMultipartUploadResult> Function(FluppyFile file): Signature for the createMultipartUpload callback.
EventEmitter = void Function(FluppyEvent event): Callback type for emitting events.
GetChunkSizeCallback = int Function(FluppyFile file): Signature for the getChunkSize callback.
GetObjectKeyCallback = String Function(FluppyFile file): Signature for the getObjectKey callback.
GetTemporarySecurityCredentialsCallback = Future<TemporaryCredentials> Function(CredentialsOptions options): Signature for the getTemporarySecurityCredentials callback.
GetUploadParametersCallback = Future<UploadParameters> Function(FluppyFile file, UploadOptions options): Signature for the getUploadParameters callback.
ListPartsCallback = Future<List<S3Part>> Function(FluppyFile file, ListPartsOptions options): Signature for the listParts callback.
ProgressCallback = void Function(UploadProgressInfo progress): Callback type for progress updates.
ShouldUseMultipartCallback = bool Function(FluppyFile file): Signature for the shouldUseMultipart callback.
SignPartCallback = Future<SignPartResult> Function(FluppyFile file, SignPartOptions options): Signature for the signPart callback.
UploadPartBytesCallback = Future<UploadPartBytesResult> Function(UploadPartBytesOptions options): Signature for the uploadPartBytes callback.

Exceptions / Errors

CancelledException: Exception thrown when an operation is cancelled.
PausedException: Exception thrown when an upload is paused.
S3ExpiredUrlException: Exception thrown when a presigned URL has expired.
S3UploadException: Exception thrown when an S3 upload fails.

fluppy library

Features

Quick Start

Classes

Enums

Mixins

Extensions

Constants

Typedefs

Exceptions / Errors

fluppy package

fluppy library