dox_storage 3.2.2
dox_storage: ^3.2.2 copied to clipboard
File storage for the Dox framework. One API for local disk, AWS S3 and S3-compatible services (R2, MinIO, Spaces), with swappable drivers.
dox_storage #
File storage for Dart. One API for local disk, AWS S3 and S3-compatible services.
Part of Dox, a web backend framework for Dart. Source code: github.com/dartondox/dox-storage.
Install #
dart pub add dox_storage
To see what is ready and what may still change, read Status and roadmap.
Use it #
import 'dart:typed_data';
import 'package:dox_storage/dox_storage.dart';
void main() async {
DriveManager drive = DriveManager(
defaultDisk: 'local',
disks: <String, DriverContract>{
'local': LocalDriver(LocalDriverConfig(root: 'storage')),
's3': S3Driver(S3DriverConfig(
bucket: 'my-bucket',
region: 'us-east-1',
accessKeyId: 'AKIA...',
secretAccessKey: '...',
)),
},
);
Disk disk = drive.use(); // the default disk
await disk.put('notes/a.txt', 'hello');
Uint8List data = await disk.get('notes/a.txt');
print(await disk.exists('notes/a.txt')); // true
await disk.append('notes/a.txt', 'world'); // "hello\nworld"
print(await disk.size('notes/a.txt')); // 11
await disk.delete('notes/a.txt');
}
Use it in a Dox app #
-
Set the disks in
lib/config/storage.dart:import 'package:dox_storage/dox_storage.dart'; StorageConfig storageConfig = StorageConfig( defaultDisk: 'local', disks: <String, Map<String, dynamic>>{ 'local': <String, dynamic>{'driver': 'local', 'root': 'storage/app'}, }, ); -
Register the provider in
lib/providers/storage_provider.dart. The generated container finds it.import 'package:dox_storage/dox_storage.dart'; import '../config/storage.dart'; class AppStorageProvider extends StorageProvider { AppStorageProvider() : super(storageConfig); } -
Use
Storage():RequestFile file = req.input('avatar'); String path = await Storage().putFile('avatars', file); // new uuid name await Storage().put('notes/a.txt', 'hello', exact: true); // this exact path return Storage().download(path, name: 'avatar.png');Serve files with
Storage.route('files')in a router. An unsigned route (signed: false) serves every file under the disk root. Keep the root a folder that holds only public uploads.
Without the provider, Storage() has one local disk in the storage folder.
Features #
- Drivers:
LocalDriver,S3Driver(AWS S3, Cloudflare R2, MinIO, DigitalOcean Spaces, GCS with HMAC keys) andMemoryDriver. put,putStream,get,getStream,copy,move,delete,listAll.files,allFiles,directories,deleteDirectoryandmissing.deleteDirectoryrefuses the root (''or/), so a bad path can not empty a disk.Storage().put(folder, bytes)andputFile(folder, file)store with a new uuid file name.Storage().put(path, contents, exact: true)writes to that exact path.putFileAs(folder, file, name)stores with your name.append,prepend,size,lastModified,makeDirectoryanddirectoryExists.makeDirectorydoes nothing on any disk that is not local (S3, memory, custom drivers), because they have no real folders.directoryExists('')(the root) is always true.- Signed download URLs, and signed upload URLs on S3. A local signed URL only works on the route of its own disk.
- Opt-in atomic local writes (
atomicWrites: true). A failed upload never leaves a partial file. - Opt-in local file modes (
permissions: true). Then visibility is the file mode: public file 0644, private file 0600, public folder 0755, private folder 0700. The mode is set before the content is written. An overwrite,appendandprependkeep the mode of the file, unless the write gives a visibility. A copy gets the write visibility, or the mode of the source, and goes through a temp file, so it never empties its own source. Each mode must be an int from 0 to 0o777, orArgumentErroris thrown. New folders get the folder mode. Visibility does not follow symlinks. It does nothing on Windows. - Big streams go up as a multipart upload. Only one part is in memory at a time.
multipartPartSizeshould be from 5 MiB to 5 GiB. Outside that rangeS3Driverprints a warning to stderr, and S3 refuses a multipart upload with parts under 5 MiB. - Opt-in
unsignedPayload: trueonS3DriverConfig(unsigned_payloadin the disk config) skips the SHA-256 hash of each body. The signature then does not cover the body, so only use it over HTTPS. putStreamhashes each part chunk by chunk in pure Dart (about 6.5 ms per MiB). A very large upload uses CPU of the request isolate, in small steps. Over HTTPS,unsignedPayload: trueremoves this cost.- Keys are checked.
.., absolute paths and null bytes throwInvalidKeyException. file.storeAs(folder, name)uses your name. Do not pass the raw client file name tostoreAs. Make your own name, likeuser-1.png.drive.fake('s3')swaps a disk for memory in tests. Check it withassertExistsandassertMissing.- AWS Signature V4 is written in this package. There is no AWS SDK dependency.
Documentation #
License #
MIT. See LICENSE.