dox_storage 3.0.0-alpha.12

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

Dox 3.x is in alpha (3.0.0-alpha.x). The API can still change before the stable release.

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.delete('notes/a.txt');
}

Use it in a Dox app

1. 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'},
     },
   );
   

2. Register the service in lib/services/storage_service.dart. The generated container finds it.

   import 'package:dox_storage/dox_storage.dart';
   
   import '../config/storage.dart';
   
   class AppStorageService extends StorageService {
     AppStorageService() : super(storageConfig);
   }
   

3. Use Storage():

   RequestFile file = req.input('avatar');
   String path = await file.store('avatars');
   return Storage().download(path);
   

   Serve files with Storage.route('files') in a router.

Without the service, Storage() has one local disk in the storage folder.

Features

• Drivers: LocalDriver, S3Driver (AWS S3, Cloudflare R2, MinIO, DigitalOcean Spaces, GCS with HMAC keys) and MemoryDriver.
• put, putStream, get, getStream, copy, move, delete, listAll.
• Signed download URLs, and signed upload URLs on S3.
• Big streams go up as a multipart upload. Only one part is in memory at a time.
• Keys are checked. .., absolute paths and null bytes throw InvalidKeyException.
• drive.fake('s3') swaps a disk for memory in tests.
• AWS Signature V4 is written in this package. There is no AWS SDK dependency.

Documentation

• Storage package
• File storage in a Dox app
• API reference

License

MIT. See LICENSE.