import 'dart:typed_data'; import '../domain/artifact_record.dart'; /// A recorded artifact's exact bytes, named and typed as the host must save or /// share them. /// /// The name is the recorded file name's basename, never a url or a directory /// path. The MIME type is the recorded media type without parameters. Only when /// the recorded value is missing or malformed does the fallback apply: the /// server url's basename, then `artifact`, and `application/octet-stream`. class ArtifactFile { const ArtifactFile({ required this.name, required this.mimeType, required this.bytes, }); final String name; final String mimeType; final Uint8List bytes; int get byteLength => bytes.length; } const String artifactFileFallbackName = 'artifact'; const String artifactFileFallbackMimeType = 'application/octet-stream'; /// Names and types one recorded artifact's fetched bytes for a file transfer. ArtifactFile artifactFileFor({ required ArtifactRecord artifact, required Uri url, required Uint8List bytes, }) => ArtifactFile( name: artifactFileName(artifact, url), mimeType: artifactFileMimeType(artifact), bytes: bytes, ); /// The recorded name without any `public/` prefix or directory component, with /// control characters replaced. An absent, dot-only or unusable name falls /// back to the resolved url's last path segment and then to `artifact`. String artifactFileName(ArtifactRecord artifact, Uri url) { final recorded = _usableBasename(artifact.name); if (recorded.isNotEmpty) return recorded; final fromUrl = _usableBasename( url.pathSegments.isEmpty ? '' : url.pathSegments.last, ); return fromUrl.isEmpty ? artifactFileFallbackName : fromUrl; } /// The recorded MIME type without parameters, lowercased, or /// `application/octet-stream` when nothing usable was recorded. String artifactFileMimeType(ArtifactRecord artifact) { final mediaType = artifact.contentType.split(';').first.trim().toLowerCase(); return _mediaType.hasMatch(mediaType) ? mediaType : artifactFileFallbackMimeType; } final RegExp _mediaType = RegExp( r"^[a-z0-9!#$&'*+.^_`|~-]+/[a-z0-9!#$&'*+.^_`|~-]+$", ); /// Whether the record carries a usable file name of its own. bool hasRecordedArtifactName(ArtifactRecord artifact) => _usableBasename(artifact.name).isNotEmpty; /// Whether the record carries a usable MIME type of its own. bool hasRecordedArtifactMimeType(ArtifactRecord artifact) { final mediaType = artifact.contentType.split(';').first.trim().toLowerCase(); return _mediaType.hasMatch(mediaType); } /// An explicit note when the recorded name or MIME type cannot be used, so the /// fallback file name/type is never silent. Null for a complete record. String? artifactFileRecordingNotice(ArtifactRecord artifact, Uri url) { final nameMissing = !hasRecordedArtifactName(artifact); final typeMissing = !hasRecordedArtifactMimeType(artifact); if (!nameMissing && !typeMissing) return null; final name = artifactFileName(artifact, url); if (nameMissing && typeMissing) { return 'No usable recorded name or MIME type; the file is saved as ' '$name ($artifactFileFallbackMimeType).'; } if (nameMissing) { return 'No usable recorded name; the file is saved as $name.'; } return 'No usable recorded MIME type; the file is saved as ' '$artifactFileFallbackMimeType.'; } String _usableBasename(String value) { final segments = value.trim().split(RegExp(r'[\\/]')); final name = segments.isEmpty ? '' : segments.last; final cleaned = name.replaceAll(RegExp(r'[\x00-\x1f\x7f]'), '_').trim(); if (cleaned == '.' || cleaned == '..') return ''; return cleaned; }