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,14 @@
 
 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
+- Support for HTTP range requests
+
 ## Usage
 
 Bind as root handler:
@@ -67,3 +75,24 @@ 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);
+}
+```

example/pubspec.lock

@@ -37,10 +37,10 @@ packages:
     dependency: transitive
     description:
       name: collection
-      sha256: "4a07be6cb69c84d677a6c3096fcf960cc3285a8330b4603e0d463d15d9bd934c"
+      sha256: ee67cb0715911d28db6bf4af1026078bd6f0128b07a5f66fb2ed94ec6783c09a
       url: "https://pub.dev"
     source: hosted
-    version: "1.17.1"
+    version: "1.18.0"
   cupertino_icons:
     dependency: "direct main"
     description:
@@ -83,14 +83,30 @@ packages:
       url: "https://pub.dev"
     source: hosted
     version: "4.0.2"
-  js:
+  leak_tracker:
     dependency: transitive
     description:
-      name: js
-      sha256: f2c445dce49627136094980615a031419f7f3eb393237e4ecd97ac15dea343f3
+      name: leak_tracker
+      sha256: "3f87a60e8c63aecc975dda1ceedbc8f24de75f09e4856ea27daf8958f2f0ce05"
       url: "https://pub.dev"
     source: hosted
-    version: "0.6.7"
+    version: "10.0.5"
+  leak_tracker_flutter_testing:
+    dependency: transitive
+    description:
+      name: leak_tracker_flutter_testing
+      sha256: "932549fb305594d82d7183ecd9fa93463e9914e1b67cacc34bc40906594a1806"
+      url: "https://pub.dev"
+    source: hosted
+    version: "3.0.5"
+  leak_tracker_testing:
+    dependency: transitive
+    description:
+      name: leak_tracker_testing
+      sha256: "6ba465d5d76e67ddf503e1161d1f4a6bc42306f9d66ca1e8f079a47290fb06d3"
+      url: "https://pub.dev"
+    source: hosted
+    version: "3.0.1"
   lints:
     dependency: transitive
     description:
@@ -103,26 +119,26 @@ packages:
     dependency: transitive
     description:
       name: matcher
-      sha256: "6501fbd55da300384b768785b83e5ce66991266cec21af89ab9ae7f5ce1c4cbb"
+      sha256: d2323aa2060500f906aa31a895b4030b6da3ebdcc5619d14ce1aada65cd161cb
       url: "https://pub.dev"
     source: hosted
-    version: "0.12.15"
+    version: "0.12.16+1"
   material_color_utilities:
     dependency: transitive
     description:
       name: material_color_utilities
-      sha256: d92141dc6fe1dad30722f9aa826c7fbc896d021d792f80678280601aff8cf724
+      sha256: f7142bb1154231d7ea5f96bc7bde4bda2a0945d2806bb11670e30b850d56bdec
       url: "https://pub.dev"
     source: hosted
-    version: "0.2.0"
+    version: "0.11.1"
   meta:
     dependency: transitive
     description:
       name: meta
-      sha256: "3c74dbf8763d36539f114c799d8a2d87343b5067e9d796ca22b5eb8437090ee3"
+      sha256: bdb68674043280c3428e9ec998512fb681678676b3c54e773629ffe74419f8c7
       url: "https://pub.dev"
     source: hosted
-    version: "1.9.1"
+    version: "1.15.0"
   mime:
     dependency: transitive
     description:
@@ -135,10 +151,10 @@ packages:
     dependency: transitive
     description:
       name: path
-      sha256: "8829d8a55c13fc0e37127c29fedf290c102f4e40ae94ada574091fe0ff96c917"
+      sha256: "087ce49c3f0dc39180befefc60fdb4acd8f8620e5682fe2476afd0b3688bb4af"
       url: "https://pub.dev"
     source: hosted
-    version: "1.8.3"
+    version: "1.9.0"
   plugin_platform_interface:
     dependency: transitive
     description:
@@ -161,7 +177,7 @@ packages:
       path: ".."
       relative: true
     source: path
-    version: "0.0.3"
+    version: "0.1.0"
   sky_engine:
     dependency: transitive
     description: flutter
@@ -171,26 +187,26 @@ packages:
     dependency: transitive
     description:
       name: source_span
-      sha256: dd904f795d4b4f3b870833847c461801f6750a9fa8e61ea5ac53f9422b31f250
+      sha256: "53e943d4206a5e30df338fd4c6e7a077e02254531b138a15aec3bd143c1a8b3c"
       url: "https://pub.dev"
     source: hosted
-    version: "1.9.1"
+    version: "1.10.0"
   stack_trace:
     dependency: transitive
     description:
       name: stack_trace
-      sha256: c3c7d8edb15bee7f0f74debd4b9c5f3c2ea86766fe4178eb2a18eb30a0bdaed5
+      sha256: "73713990125a6d93122541237550ee3352a2d84baad52d375a4cad2eb9b7ce0b"
       url: "https://pub.dev"
     source: hosted
-    version: "1.11.0"
+    version: "1.11.1"
   stream_channel:
     dependency: transitive
     description:
       name: stream_channel
-      sha256: "83615bee9045c1d322bbbd1ba209b7a749c2cbcdcb3fdd1df8eb488b3279c1c8"
+      sha256: ba2aa5d8cc609d96bbb2899c28934f9e1af5cddbd60a827822ea467161eb54e7
       url: "https://pub.dev"
     source: hosted
-    version: "2.1.1"
+    version: "2.1.2"
   string_scanner:
     dependency: transitive
     description:
@@ -211,10 +227,10 @@ packages:
     dependency: transitive
     description:
       name: test_api
-      sha256: eb6ac1540b26de412b3403a163d919ba86f6a973fe6cc50ae3541b80092fdcfb
+      sha256: "5b8a98dafc4d5c4c9c72d8b31ab2b23fc13422348d2997120294d3bac86b4ddb"
       url: "https://pub.dev"
     source: hosted
-    version: "0.5.1"
+    version: "0.7.2"
   typed_data:
     dependency: transitive
     description:
@@ -231,6 +247,14 @@ packages:
       url: "https://pub.dev"
     source: hosted
     version: "2.1.4"
+  vm_service:
+    dependency: transitive
+    description:
+      name: vm_service
+      sha256: "5c5f338a667b4c644744b661f309fb8080bb94b18a7e91ef1dbd343bed00ed6d"
+      url: "https://pub.dev"
+    source: hosted
+    version: "14.2.5"
   webview_flutter:
     dependency: "direct main"
     description:
@@ -264,5 +288,5 @@ packages:
     source: hosted
     version: "3.0.2"
 sdks:
-  dart: ">=3.0.0-0 <4.0.0"
-  flutter: ">=3.0.0"
+  dart: ">=3.3.0 <4.0.0"
+  flutter: ">=3.18.0-18.0.pre.54"

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,16 @@ 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).
+///
 Handler createAssetHandler(
     {String? defaultDocument,
     String rootPath = 'assets',
-    MimeTypeResolver? contentTypeResolver}) {
+    MimeTypeResolver? contentTypeResolver,
+    bool enableCaching = false,
+    int maxAge = _defaultMaxAge}) {
   final mimeResolver = contentTypeResolver ?? _defaultMimeTypeResolver;
 
   return (Request request) async {
@@ -52,6 +62,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 (request.headers.containsKey('range')) {
+      return _handleRangeRequest(request, body, headers);
+    }
+
     return Response.ok((request.method == 'HEAD') ? null : body,
         headers: headers);
   };
@@ -66,3 +86,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_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: '/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: '/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: '/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/default_document_test.dart

@@ -17,7 +17,7 @@ void main() {
       final request = makeRequest();
 
       final response = await handler(request);
-      expect(response.statusCode, HttpStatus.notFound);
+      expect(response.statusCode, equals(HttpStatus.notFound));
     });
   });
 
@@ -28,7 +28,7 @@ void main() {
       final request = makeRequest();
 
       final response = await handler(request);
-      expect(response.statusCode, HttpStatus.ok);
+      expect(response.statusCode, equals(HttpStatus.ok));
     });
   });
 }