AdvancedFileOutput: Added fileHeader and fileFooter options

Author: Bungeefan

lib/src/outputs/advanced_file_output.dart

@@ -57,10 +57,17 @@ class AdvancedFileOutput extends LogOutput {
   /// The [latestFileName] will not be counted. The default [fileSorter] strategy is
   /// sorting by last modified date, beware that could be not reliable in some
   /// platforms and/or filesystems.
+  ///
+  /// [fileHeader] and [fileFooter] can be used to respectively add a header
+  /// or footer to the file when opening/closing the file sink.
+  /// (Please note that this happens not only when files are rotated but also
+  /// on every start and shutdown of your application!)
   AdvancedFileOutput({
     required String path,
     bool overrideExisting = false,
     Encoding encoding = utf8,
+    this.fileHeader,
+    this.fileFooter,
     List<Level>? writeImmediately,
     Duration maxDelay = const Duration(seconds: 2),
     int maxBufferSize = 2000,
@@ -96,6 +103,9 @@ class AdvancedFileOutput extends LogOutput {
   final bool _overrideExisting;
   final Encoding _encoding;
 
+  String? fileHeader;
+  String? fileFooter;
+
   final List<Level> _writeImmediately;
   final Duration _maxDelay;
   final int _maxFileSizeKB;
@@ -200,9 +210,17 @@ class AdvancedFileOutput extends LogOutput {
       mode: _overrideExisting ? FileMode.writeOnly : FileMode.writeOnlyAppend,
       encoding: _encoding,
     );
+
+    if (fileHeader != null) {
+      _sink?.writeln(fileHeader);
+    }
   }
 
   Future<void> _closeSink() async {
+    if (fileFooter != null) {
+      _sink?.writeln(fileFooter);
+    }
+
     await _sink?.flush();
     await _sink?.close();
     _sink = null; // Explicitly set null until assigned again

lib/src/outputs/advanced_file_output_stub.dart

@@ -52,10 +52,17 @@ class AdvancedFileOutput extends LogOutput {
   /// The [latestFileName] will not be counted. The default [fileSorter] strategy is
   /// sorting by last modified date, beware that could be not reliable in some
   /// platforms and/or filesystems.
+  ///
+  /// [fileHeader] and [fileFooter] can be used to respectively add a header
+  /// or footer to the file when opening/closing the file sink.
+  /// (Please note that this happens not only when files are rotated but also
+  /// on every start and shutdown of your application!)
   AdvancedFileOutput({
     required String path,
     bool overrideExisting = false,
     Encoding encoding = utf8,
+    String? fileHeader,
+    String? fileFooter,
     List<Level>? writeImmediately,
     Duration maxDelay = const Duration(seconds: 2),
     int maxBufferSize = 2000,

test/outputs/advanced_file_output_test.dart

@@ -154,6 +154,32 @@ void main() {
     expect(await rotatedFile.readAsString(), contains("2"));
   });
 
+  test('Rolling files with header/footer', () async {
+    const fileHeader = "TEST-HEADER";
+    const fileFooter = "TEST-FOOTER";
+
+    var output = AdvancedFileOutput(
+      path: dir.path,
+      maxFileSizeKB: 1,
+      maxRotatedFilesCount: 1,
+      fileHeader: fileHeader,
+      fileFooter: fileFooter,
+    );
+
+    await output.init();
+    final event0 =
+        OutputEvent(LogEvent(Level.fatal, ""), ["Header and Footer Test"]);
+    output.output(event0);
+    await output.destroy();
+
+    // Give the OS a chance to flush to the file system (should reduce flakiness)
+    await Future.delayed(const Duration(milliseconds: 1000));
+
+    final latestFile = File('${dir.path}/latest.log');
+    expect(await latestFile.readAsString(), startsWith(fileHeader));
+    expect(await latestFile.readAsString(), endsWith("$fileFooter\n"));
+  });
+
   test('Rolling files with custom file sorter', () async {
     var output = AdvancedFileOutput(
       path: dir.path,