feat(llc)!: rework attachment uploads around AttachmentUploadTask

packages/stream_core/CHANGELOG.md

@@ -25,7 +25,13 @@
 - `Result.getOrElse`, `getOrDefault`, `recover` and `recoverCatching` return the result's own type and no longer take a type parameter. To widen, widen the result (`Result<num> widened = intResult`) or use `fold`
 - Replaced the logger: `StreamLogger` is the handle you write with and a `StreamLogHandler` is where records go, so `Priority`, `MessageBuilder`, `Tag`, `IsLoggableValidator` and `Finder` are renamed or gone
 - `LoggingInterceptor` writes through the logger rather than printing, so it is silent until an app asks for records. Its `logPrint` is now optional, and it takes a `tag`
-- The package no longer re-exports `dart:typed_data`, so code that reached `Uint8List` through `package:stream_core/stream_core.dart` must import `dart:typed_data` itself
+- Reworked attachment uploads around `AttachmentUploadTask`: `StreamAttachmentUploader.upload` returns the running task rather than a `Future`, and `uploadBatch` returns an `AttachmentUploadBatch`. `CancelToken` and progress callbacks are gone from the public API
+- Removed `StreamAttachment.uploadState`. Where an upload has got to lives on the task running it, not on the attachment
+- Replaced the `UploadState*` classes with `UploadQueued`, `UploadPreparing`, `UploadInProgress`, `UploadSuccess`, `UploadFailed` and `UploadCancelled`, constructed directly rather than through named constructors. `UploadInProgress.progress` is an `UploadProgress` in bytes rather than a `double`, and `UploadFailed.error` is a `StreamException`
+- Removed `AttachmentUploadException`. A failed upload carries the `StreamException` that stopped it, and a cancelled one a `StreamNetworkException` with `isCancelled` set
+- Removed the `OnUploadProgress` and `OnBatchUploadProgress` callbacks along with the `StreamAttachmentUploaderBatch` extension. Progress arrives on `AttachmentUploadTask.state` and `AttachmentUploadBatch.state`, so it can never disagree with the lifecycle
+- `uploadBatch`'s `maxConcurrent` now defaults to `3` rather than `5`
+- `UploadedAttachment` compares by value rather than by identity
 
 ### ✨ Features
 
@@ -49,6 +55,8 @@
 - Added `ConnectUserDetailsRequest.fromUser`, which builds the details a client may send from a `User`
 - Added `StreamWebSocketClient.dispose`, which closes the connection along with `events` and `connectionState`; the client is now `Disposable`, and `connect` throws a `StateError` afterwards
 - Added `InFlightCache`, which hands concurrent callers asking for the same key the one call already in flight, and its outcome, success or failure alike
+- Added `AttachmentUploadTask`, one upload as an object: `state` carries the whole lifecycle including byte progress, `result` settles once and never throws, and `cancel` calls it off at once
+- Added `AttachmentUploadBatch`, which uploads several attachments under a concurrency limit, aggregates byte-weighted progress, and finishes as a sealed `BatchUploadResult` — `BatchUploadCompleted`, `BatchUploadStoppedOnError` or `BatchUploadCancelled` — carrying one outcome per attachment in input order
 
 ### 🐛 Bug Fixes
 

packages/stream_core/lib/src/attachment.dart

@@ -1,8 +1,11 @@
 export 'attachment/attachment.dart';
 export 'attachment/attachment_file.dart';
 export 'attachment/attachment_type.dart';
-export 'attachment/attachment_upload_state.dart';
 export 'attachment/cdn/cdn_client.dart';
 export 'attachment/cdn/uploaded_file.dart';
+export 'attachment/uploader/attachment_upload_batch.dart';
+export 'attachment/uploader/attachment_upload_state.dart';
+export 'attachment/uploader/attachment_upload_task.dart';
 export 'attachment/uploader/attachment_uploader.dart';
+export 'attachment/uploader/batch_upload_state.dart';
 export 'attachment/uploader/uploaded_attachment.dart';

packages/stream_core/lib/src/attachment/attachment.dart

@@ -2,13 +2,14 @@ import 'package:uuid/uuid.dart';
 
 import 'attachment_file.dart';
 import 'attachment_type.dart';
-import 'attachment_upload_state.dart';
 
-/// Represents a file attachment with type information and upload state.
+/// Represents a file attachment with type information.
 ///
-/// Combines an [AttachmentFile] with its [AttachmentType] and tracks the
-/// upload progress through [AttachmentUploadState]. This class provides
-/// a complete representation of an attachment throughout its lifecycle.
+/// Combines an [AttachmentFile] with its [AttachmentType], and is what an
+/// upload is asked for: it carries the local [id] the upload is addressed by,
+/// the [file] to send, and the [custom] data handed back on the uploaded
+/// attachment. Where the upload has got to lives on the task running it, not
+/// here.
 ///
 /// Example usage:
 /// ```dart
@@ -49,14 +50,12 @@ class StreamAttachment {
   /// If not provided, a UUID v4 will be automatically generated.
   /// The [type] specifies what kind of attachment this is.
   /// The [file] contains the actual file data and metadata.
-  /// The [uploadState] tracks the upload progress, defaulting to preparing.
   /// The [custom] allows storing arbitrary key-value pairs for additional
   /// metadata specific to your application's needs.
   StreamAttachment({
     String? id,
     required this.type,
     required this.file,
-    this.uploadState = const AttachmentUploadState.preparing(),
     this.custom,
   }) : id = id ?? const Uuid().v4();
 
@@ -72,9 +71,6 @@ class StreamAttachment {
   /// The file data and metadata.
   final AttachmentFile file;
 
-  /// The current upload state of this attachment.
-  final AttachmentUploadState uploadState;
-
   /// Optional custom data for storing arbitrary key-value pairs.
   ///
   /// This allows applications to attach additional metadata to attachments
@@ -90,14 +86,12 @@ class StreamAttachment {
   StreamAttachment copyWith({
     AttachmentType? type,
     AttachmentFile? file,
-    AttachmentUploadState? uploadState,
     Map<String, Object?>? custom,
   }) {
     return StreamAttachment(
       id: id, // ID is preserved and cannot be changed
       type: type ?? this.type,
       file: file ?? this.file,
-      uploadState: uploadState ?? this.uploadState,
       custom: custom ?? this.custom,
     );
   }