Implement cache control support and range requests

Author: r8

CHANGELOG.md

@@ -1,3 +1,8 @@
+## 0.1.0
+
+* Added HTTP cache-control support
+* Added HTTP range request support for partial content
+
 ## 0.0.4
 
 * Update library metadata

README.md

@@ -7,6 +7,13 @@
 
 A simple handler for the Shelf ecosystem to serve files from Flutter assets.
 
+## Features
+- Serves files from Flutter assets
+- Support for default documents (like index.html)
+- Content type detection
+- Optional caching support with customizable max-age
+- Optional support for HTTP range requests
+
 ## Usage
 
 Bind as root handler:
@@ -67,3 +74,63 @@ void main() {
   io.serve(app, 'localhost', 8080);
 }
 ```
+
+## Advanced Usage
+
+### Caching
+
+Enable browser caching for better performance:
+
+```dart
+import 'package:shelf/shelf_io.dart' as io;
+import 'package:shelf_flutter_asset/shelf_flutter_asset.dart';
+
+void main() {
+  var assetHandler = createAssetHandler(
+    defaultDocument: 'index.html',
+    enableCaching: true,    // Enable caching
+    maxAge: 3600,           // Cache for 1 hour (in seconds)
+  );
+
+  io.serve(assetHandler, 'localhost', 8080);
+}
+```
+
+### Range Requests
+
+Support HTTP range requests for media files:
+
+```dart
+import 'package:shelf/shelf_io.dart' as io;
+import 'package:shelf_flutter_asset/shelf_flutter_asset.dart';
+
+void main() {
+  var assetHandler = createAssetHandler(
+    defaultDocument: 'index.html',
+    enableRangeRequests: true,  // Enable range requests for media streaming
+  );
+
+  io.serve(assetHandler, 'localhost', 8080);
+}
+```
+
+### Combined Features
+
+Use all features together:
+
+```dart
+import 'package:shelf/shelf_io.dart' as io;
+import 'package:shelf_flutter_asset/shelf_flutter_asset.dart';
+
+void main() {
+  var assetHandler = createAssetHandler(
+    defaultDocument: 'index.html',
+    rootPath: 'assets/web',
+    enableCaching: true,
+    maxAge: 86400,              // Cache for 1 day
+    enableRangeRequests: true,
+  );
+
+  io.serve(assetHandler, 'localhost', 8080);
+}
+```

lib/shelf_flutter_asset.dart

@@ -1,4 +1,5 @@
 import 'dart:io';
+import 'dart:math';
 
 import 'package:flutter/services.dart';
 import 'package:mime/mime.dart';
@@ -8,6 +9,9 @@ import 'package:shelf/shelf.dart';
 /// The default resolver for MIME types.
 final _defaultMimeTypeResolver = MimeTypeResolver();
 
+/// Default cache duration (1 hour)
+const _defaultMaxAge = 3600;
+
 /// Creates a Shelf [Handler] that serves files from Flutter assets.
 ///
 /// If requested resource does not exist and [defaultDocument] is specified,
@@ -20,10 +24,18 @@ final _defaultMimeTypeResolver = MimeTypeResolver();
 /// If your assets are not in the standard `assets` directory,
 /// or you want to share only subtree of the assets path structure,
 /// you may use [rootPath] argument to set the root directory for your handler.
+///
+/// Set [enableCaching] to true to add cache-control headers with [maxAge] seconds
+/// (defaults to 1 hour).
+///
+/// Set [enableRangeRequests] to true to support HTTP range requests for partial content.
 Handler createAssetHandler(
     {String? defaultDocument,
     String rootPath = 'assets',
-    MimeTypeResolver? contentTypeResolver}) {
+    MimeTypeResolver? contentTypeResolver,
+    bool enableCaching = false,
+    int maxAge = _defaultMaxAge,
+    bool enableRangeRequests = false}) {
   final mimeResolver = contentTypeResolver ?? _defaultMimeTypeResolver;
 
   return (Request request) async {
@@ -52,6 +64,16 @@ Handler createAssetHandler(
       if (contentType != null) HttpHeaders.contentTypeHeader: contentType,
     };
 
+    // Add cache control headers if enabled
+    if (enableCaching) {
+      headers[HttpHeaders.cacheControlHeader] = 'max-age=$maxAge, public';
+    }
+
+    // Handle range requests if enabled
+    if (enableRangeRequests && request.headers.containsKey('range')) {
+      return _handleRangeRequest(request, body, headers);
+    }
+
     return Response.ok((request.method == 'HEAD') ? null : body,
         headers: headers);
   };
@@ -66,3 +88,46 @@ Future<Uint8List?> _loadResource(String key) async {
 
   return null;
 }
+
+/// Handles HTTP range requests by parsing the Range header and returning
+/// the appropriate partial content response.
+Response _handleRangeRequest(
+    Request request, Uint8List body, Map<String, String> headers) {
+  final rangeHeader = request.headers['range']!;
+  final match = RegExp(r'bytes=(\d*)-(\d*)').firstMatch(rangeHeader);
+
+  if (match == null) {
+    return Response(416, headers: headers); // Range Not Satisfiable
+  }
+
+  final startStr = match.group(1);
+  final endStr = match.group(2);
+
+  int start = startStr!.isEmpty ? 0 : int.parse(startStr);
+  int end = endStr!.isEmpty ? body.length - 1 : int.parse(endStr);
+
+  // Validate the range
+  if (start >= body.length || end >= body.length || start > end) {
+    return Response(416, headers: {
+      ...headers,
+      'content-range': 'bytes */${body.length}',
+    });
+  }
+
+  // Limit the length to the actual body size
+  end = min(end, body.length - 1);
+  
+  final length = end - start + 1;
+  final rangeBody = body.sublist(start, end + 1);
+
+  final rangeHeaders = {
+    ...headers,
+    HttpHeaders.contentLengthHeader: '$length',
+    'content-range': 'bytes $start-$end/${body.length}',
+    'accept-ranges': 'bytes',
+  };
+
+  return Response(206, // Partial Content
+      body: (request.method == 'HEAD') ? null : rangeBody,
+      headers: rangeHeaders);
+}

pubspec.yaml

@@ -1,6 +1,6 @@
 name: shelf_flutter_asset
 description: A simple handler for the Shelf ecosystem to serve files from Flutter assets.
-version: 0.0.4
+version: 0.1.0
 homepage: https://github.com/r8/shelf_flutter_asset
 repository: https://github.com/r8/shelf_flutter_asset
 issue_tracker: https://github.com/r8/shelf_flutter_asset/issues

test/cache_support_test.dart

@@ -0,0 +1,49 @@
+import 'package:flutter_test/flutter_test.dart';
+import 'package:shelf/shelf.dart';
+import 'package:shelf_flutter_asset/shelf_flutter_asset.dart';
+
+import 'test_util.dart';
+
+void main() {
+  setUpAll(() async {
+    setUpAssets();
+  });
+
+  group('Cache Support', () {
+    test('cache-control headers not present by default', () async {
+      final handler = createAssetHandler();
+      final request = makeRequest(path: '/assets/index.html');
+      final response = await handler(request);
+
+      expect(response.statusCode, equals(200));
+      expect(response.headers['cache-control'], isNull);
+    });
+
+    test('cache-control headers present when enabled', () async {
+      final handler = createAssetHandler(enableCaching: true, maxAge: 3600);
+      final request = makeRequest(path: '/assets/index.html');
+      final response = await handler(request);
+
+      expect(response.statusCode, equals(200));
+      expect(response.headers['cache-control'], equals('max-age=3600, public'));
+    });
+
+    test('cache-control headers use custom maxAge', () async {
+      final handler = createAssetHandler(enableCaching: true, maxAge: 86400);
+      final request = makeRequest(path: '/assets/index.html');
+      final response = await handler(request);
+
+      expect(response.statusCode, equals(200));
+      expect(response.headers['cache-control'], equals('max-age=86400, public'));
+    });
+
+    test('cache-control headers are not added for 404 responses', () async {
+      final handler = createAssetHandler(enableCaching: true);
+      final request = makeRequest(path: '/assets/not-found.html');
+      final response = await handler(request);
+
+      expect(response.statusCode, equals(404));
+      expect(response.headers['cache-control'], isNull);
+    });
+  });
+}

test/range_request_test.dart

@@ -0,0 +1,102 @@
+import 'dart:convert';
+import 'dart:io';
+
+import 'package:flutter_test/flutter_test.dart';
+import 'package:shelf/shelf.dart';
+import 'package:shelf_flutter_asset/shelf_flutter_asset.dart';
+
+import 'test_util.dart';
+
+void main() {
+  setUpAll(() async {
+    setUpAssets();
+  });
+
+  group('Range Requests', () {
+    test('range request support disabled by default', () async {
+      final handler = createAssetHandler();
+      final request = makeRequest(
+        path: '/assets/index.html',
+        headers: {'range': 'bytes=0-10'},
+      );
+      final response = await handler(request);
+
+      expect(response.statusCode, equals(200));
+      expect(response.headers['accept-ranges'], isNull);
+      expect(response.headers['content-range'], isNull);
+    });
+
+    test('valid range request returns partial content', () async {
+      final handler = createAssetHandler(enableRangeRequests: true);
+      final request = makeRequest(
+        path: '/assets/index.html',
+        headers: {'range': 'bytes=0-10'},
+      );
+      final response = await handler(request);
+      
+      expect(response.statusCode, equals(206));
+      expect(response.headers['accept-ranges'], equals('bytes'));
+      expect(response.headers['content-range'], isNotNull);
+      expect(response.headers['content-length'], equals('11'));
+      
+      // Verify content is correct
+      final body = await response.readAsString();
+      expect(body.length, equals(11));
+    });
+
+    test('invalid range format returns 416', () async {
+      final handler = createAssetHandler(enableRangeRequests: true);
+      final request = makeRequest(
+        path: '/assets/index.html',
+        headers: {'range': 'invalid-range-format'},
+      );
+      final response = await handler(request);
+      
+      expect(response.statusCode, equals(416));
+    });
+    
+    test('range outside file bounds returns 416', () async {
+      final handler = createAssetHandler(enableRangeRequests: true);
+      final request = makeRequest(
+        path: '/assets/index.html',
+        headers: {'range': 'bytes=100000-200000'},
+      );
+      final response = await handler(request);
+      
+      expect(response.statusCode, equals(416));
+      expect(response.headers['content-range'], contains('*'));
+    });
+    
+    test('open-ended range request works', () async {
+      final handler = createAssetHandler(enableRangeRequests: true);
+      final request = makeRequest(
+        path: '/assets/index.html',
+        headers: {'range': 'bytes=10-'},
+      );
+      final response = await handler(request);
+      
+      expect(response.statusCode, equals(206));
+      expect(response.headers['accept-ranges'], equals('bytes'));
+      expect(response.headers['content-range'], isNotNull);
+    });
+
+    test('head request with range returns no body', () async {
+      final handler = createAssetHandler(enableRangeRequests: true);
+      final request = makeRequest(
+        method: 'HEAD',
+        path: '/assets/index.html',
+        headers: {'range': 'bytes=0-10'},
+      );
+      final response = await handler(request);
+      
+      expect(response.statusCode, equals(206));
+      expect(response.headers['accept-ranges'], equals('bytes'));
+      expect(response.headers['content-range'], isNotNull);
+      expect(response.headers['content-length'], equals('11'));
+      
+      // Verify body is empty for HEAD request
+      final body = await response.read().toList();
+      expect(body, isEmpty);
+    });
+  });
+}

test/test_util.dart

@@ -21,6 +21,14 @@ setUpAssets() {
   });
 }
 
-Request makeRequest({String method = 'GET', String path = '/'}) {
-  return Request(method, Uri(scheme: 'http', host: 'localhost', path: path));
+Request makeRequest({
+  String method = 'GET', 
+  String path = '/',
+  Map<String, String>? headers,
+}) {
+  return Request(
+    method, 
+    Uri(scheme: 'http', host: 'localhost', path: path),
+    headers: headers,
+  );
 }