FileLifecycleHooks

.gitignore

@@ -26,6 +26,9 @@ bld/
 # Uncomment if you have tasks that create the project's static files in wwwroot
 #wwwroot/
 
+# Rider cache/options directory
+.idea
+
 # MSTest test Results
 [Tt]est[Rr]esult*/
 [Bb]uild[Ll]og.*

src/Serilog.Sinks.File/FileLifecycleHooks.cs

@@ -0,0 +1,37 @@
+// Copyright 2019 Serilog Contributors
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+using System.IO;
+
+namespace Serilog
+{
+    /// <summary>
+    /// Enables hooking into log file lifecycle events.
+    /// </summary>
+    public abstract class FileLifecycleHooks
+    {
+        /// <summary>
+        /// Initialize or wrap the <paramref name="underlyingStream"/> opened on the log file. This can be used to write
+        /// file headers, or wrap the stream in another that adds buffering, compression, encryption, etc. The underlying
+        /// file may or may not be empty when this method is called.
+        /// </summary>
+        /// <remarks>
+        /// A value must be returned from overrides of this method. Serilog will flush and/or dispose the returned value, but will not
+        /// dispose the stream initially passed in unless it is itself returned.
+        /// </remarks>
+        /// <param name="underlyingStream">The underlying <see cref="Stream"/> opened on the log file.</param>
+        /// <returns>The <see cref="Stream"/> Serilog should use when writing events to the log file.</returns>
+        public virtual Stream OnOpened(Stream underlyingStream) => underlyingStream;
+    }
+}

src/Serilog.Sinks.File/FileLoggerConfigurationExtensions.cs

@@ -135,11 +135,12 @@ public static LoggerConfiguration File(
         /// <param name="shared">Allow the log file to be shared by multiple processes. The default is false.</param>
         /// <param name="flushToDiskInterval">If provided, a full disk flush will be performed periodically at the specified interval.</param>
         /// <param name="rollingInterval">The interval at which logging will roll over to a new file.</param>
-        /// <param name="rollOnFileSizeLimit">If <code>true</code>, a new file will be created when the file size limit is reached. Filenames 
+        /// <param name="rollOnFileSizeLimit">If <code>true</code>, a new file will be created when the file size limit is reached. Filenames
         /// will have a number appended in the format <code>_NNN</code>, with the first filename given no number.</param>
         /// <param name="retainedFileCountLimit">The maximum number of log files that will be retained,
         /// including the current log file. For unlimited retention, pass null. The default is 31.</param>
         /// <param name="encoding">Character encoding used to write the text file. The default is UTF-8 without BOM.</param>
+        /// <param name="hooks">Optionally enables hooking into log file lifecycle events.</param>
         /// <returns>Configuration object allowing method chaining.</returns>
         /// <remarks>The file will be written using the UTF-8 character set.</remarks>
         public static LoggerConfiguration File(
@@ -156,7 +157,8 @@ public static LoggerConfiguration File(
             RollingInterval rollingInterval = RollingInterval.Infinite,
             bool rollOnFileSizeLimit = false,
             int? retainedFileCountLimit = DefaultRetainedFileCountLimit,
-            Encoding encoding = null)
+            Encoding encoding = null,
+            FileLifecycleHooks hooks = null)
         {
             if (sinkConfiguration == null) throw new ArgumentNullException(nameof(sinkConfiguration));
             if (path == null) throw new ArgumentNullException(nameof(path));
@@ -165,7 +167,7 @@ public static LoggerConfiguration File(
             var formatter = new MessageTemplateTextFormatter(outputTemplate, formatProvider);
             return File(sinkConfiguration, formatter, path, restrictedToMinimumLevel, fileSizeLimitBytes,
                 levelSwitch, buffered, shared, flushToDiskInterval,
-                rollingInterval, rollOnFileSizeLimit, retainedFileCountLimit, encoding);
+                rollingInterval, rollOnFileSizeLimit, retainedFileCountLimit, encoding, hooks);
         }
 
         /// <summary>
@@ -174,7 +176,7 @@ public static LoggerConfiguration File(
         /// <param name="sinkConfiguration">Logger sink configuration.</param>
         /// <param name="formatter">A formatter, such as <see cref="JsonFormatter"/>, to convert the log events into
         /// text for the file. If control of regular text formatting is required, use the other
-        /// overload of <see cref="File(LoggerSinkConfiguration, string, LogEventLevel, string, IFormatProvider, long?, LoggingLevelSwitch, bool, bool, TimeSpan?, RollingInterval, bool, int?, Encoding)"/>
+        /// overload of <see cref="File(LoggerSinkConfiguration, string, LogEventLevel, string, IFormatProvider, long?, LoggingLevelSwitch, bool, bool, TimeSpan?, RollingInterval, bool, int?, Encoding, FileLifecycleHooks)"/>
         /// and specify the outputTemplate parameter instead.
         /// </param>
         /// <param name="path">Path to the file.</param>
@@ -190,11 +192,12 @@ public static LoggerConfiguration File(
         /// <param name="shared">Allow the log file to be shared by multiple processes. The default is false.</param>
         /// <param name="flushToDiskInterval">If provided, a full disk flush will be performed periodically at the specified interval.</param>
         /// <param name="rollingInterval">The interval at which logging will roll over to a new file.</param>
-        /// <param name="rollOnFileSizeLimit">If <code>true</code>, a new file will be created when the file size limit is reached. Filenames 
+        /// <param name="rollOnFileSizeLimit">If <code>true</code>, a new file will be created when the file size limit is reached. Filenames
         /// will have a number appended in the format <code>_NNN</code>, with the first filename given no number.</param>
         /// <param name="retainedFileCountLimit">The maximum number of log files that will be retained,
         /// including the current log file. For unlimited retention, pass null. The default is 31.</param>
         /// <param name="encoding">Character encoding used to write the text file. The default is UTF-8 without BOM.</param>
+        /// <param name="hooks">Optionally enables hooking into log file lifecycle events.</param>
         /// <returns>Configuration object allowing method chaining.</returns>
         /// <remarks>The file will be written using the UTF-8 character set.</remarks>
         public static LoggerConfiguration File(
@@ -210,10 +213,12 @@ public static LoggerConfiguration File(
             RollingInterval rollingInterval = RollingInterval.Infinite,
             bool rollOnFileSizeLimit = false,
             int? retainedFileCountLimit = DefaultRetainedFileCountLimit,
-            Encoding encoding = null)
+            Encoding encoding = null,
+            FileLifecycleHooks hooks = null)
         {
             return ConfigureFile(sinkConfiguration.Sink, formatter, path, restrictedToMinimumLevel, fileSizeLimitBytes, levelSwitch,
-                buffered, false, shared, flushToDiskInterval, encoding, rollingInterval, rollOnFileSizeLimit, retainedFileCountLimit);
+                buffered, false, shared, flushToDiskInterval, encoding, rollingInterval, rollOnFileSizeLimit,
+                retainedFileCountLimit, hooks);
         }
 
         /// <summary>
@@ -270,7 +275,7 @@ public static LoggerConfiguration File(
             LoggingLevelSwitch levelSwitch = null)
         {
             return ConfigureFile(sinkConfiguration.Sink, formatter, path, restrictedToMinimumLevel, null, levelSwitch, false, true,
-                false, null, null, RollingInterval.Infinite, false, null);
+                false, null, null, RollingInterval.Infinite, false, null, null);
         }
 
         static LoggerConfiguration ConfigureFile(
@@ -287,35 +292,37 @@ static LoggerConfiguration ConfigureFile(
             Encoding encoding,
             RollingInterval rollingInterval,
             bool rollOnFileSizeLimit,
-            int? retainedFileCountLimit)
+            int? retainedFileCountLimit,
+            FileLifecycleHooks hooks)
         {
             if (addSink == null) throw new ArgumentNullException(nameof(addSink));
             if (formatter == null) throw new ArgumentNullException(nameof(formatter));
             if (path == null) throw new ArgumentNullException(nameof(path));
             if (fileSizeLimitBytes.HasValue && fileSizeLimitBytes < 0) throw new ArgumentException("Negative value provided; file size limit must be non-negative.", nameof(fileSizeLimitBytes));
             if (retainedFileCountLimit.HasValue && retainedFileCountLimit < 1) throw new ArgumentException("At least one file must be retained.", nameof(retainedFileCountLimit));
             if (shared && buffered) throw new ArgumentException("Buffered writes are not available when file sharing is enabled.", nameof(buffered));
+            if (shared && hooks != null) throw new ArgumentException("File lifecycle hooks are not currently supported for shared log files.", nameof(hooks));
 
             ILogEventSink sink;
 
             if (rollOnFileSizeLimit || rollingInterval != RollingInterval.Infinite)
             {
-                sink = new RollingFileSink(path, formatter, fileSizeLimitBytes, retainedFileCountLimit, encoding, buffered, shared, rollingInterval, rollOnFileSizeLimit);
+                sink = new RollingFileSink(path, formatter, fileSizeLimitBytes, retainedFileCountLimit, encoding, buffered, shared, rollingInterval, rollOnFileSizeLimit, hooks);
             }
             else
             {
                 try
                 {
-#pragma warning disable 618
                     if (shared)
                     {
-                        sink = new SharedFileSink(path, formatter, fileSizeLimitBytes);
+#pragma warning disable 618
+                        sink = new SharedFileSink(path, formatter, fileSizeLimitBytes, encoding);
+#pragma warning restore 618
                     }
                     else
                     {
-                        sink = new FileSink(path, formatter, fileSizeLimitBytes, buffered: buffered);
+                        sink = new FileSink(path, formatter, fileSizeLimitBytes, encoding, buffered, hooks);
                     }
-#pragma warning restore 618
                 }
                 catch (Exception ex)
                 {

src/Serilog.Sinks.File/Sinks/File/FileSink.cs

@@ -1,4 +1,4 @@
-// Copyright 2013-2016 Serilog Contributors
+// Copyright 2013-2016 Serilog Contributors
 //
 // Licensed under the Apache License, Version 2.0 (the "License");
 // you may not use this file except in compliance with the License.
@@ -23,7 +23,6 @@ namespace Serilog.Sinks.File
     /// <summary>
     /// Write log events to a disk file.
     /// </summary>
-    [Obsolete("This type will be removed from the public API in a future version; use `WriteTo.File()` instead.")]
     public sealed class FileSink : IFileSink, IDisposable
     {
         readonly TextWriter _output;
@@ -44,15 +43,26 @@ public sealed class FileSink : IFileSink, IDisposable
         /// <param name="buffered">Indicates if flushing to the output file can be buffered or not. The default
         /// is false.</param>
         /// <returns>Configuration object allowing method chaining.</returns>
-        /// <remarks>The file will be written using the UTF-8 character set.</remarks>
+        /// <remarks>This constructor preserves compatibility with early versions of the public API. New code should not depend on this type.</remarks>
         /// <exception cref="IOException"></exception>
+        [Obsolete("This type and constructor will be removed from the public API in a future version; use `WriteTo.File()` instead.")]
         public FileSink(string path, ITextFormatter textFormatter, long? fileSizeLimitBytes, Encoding encoding = null, bool buffered = false)
+            : this(path, textFormatter, fileSizeLimitBytes, encoding, buffered, null)
+        {
+        }
+
+        // This overload should be used internally; the overload above maintains compatibility with the earlier public API.
+        internal FileSink(
+            string path,
+            ITextFormatter textFormatter,
+            long? fileSizeLimitBytes,
+            Encoding encoding,
+            bool buffered,
+            FileLifecycleHooks hooks)
         {
             if (path == null) throw new ArgumentNullException(nameof(path));
-            if (textFormatter == null) throw new ArgumentNullException(nameof(textFormatter));
             if (fileSizeLimitBytes.HasValue && fileSizeLimitBytes < 0) throw new ArgumentException("Negative value provided; file size limit must be non-negative.");
-
-            _textFormatter = textFormatter;
+            _textFormatter = textFormatter ?? throw new ArgumentNullException(nameof(textFormatter));
             _fileSizeLimitBytes = fileSizeLimitBytes;
             _buffered = buffered;
 
@@ -68,6 +78,12 @@ public FileSink(string path, ITextFormatter textFormatter, long? fileSizeLimitBy
                 outputStream = _countingStreamWrapper = new WriteCountingStream(_underlyingStream);
             }
 
+            if (hooks != null)
+            {
+                outputStream = hooks.OnOpened(outputStream) ??
+                               throw new InvalidOperationException($"The file lifecycle hooks `{nameof(FileLifecycleHooks.OnOpened)}()` returned `null` when called with the output stream.");
+            }
+
             _output = new StreamWriter(outputStream, encoding ?? new UTF8Encoding(encoderShouldEmitUTF8Identifier: false));
         }
 

src/Serilog.Sinks.File/Sinks/File/RollingFileSink.cs

@@ -12,8 +12,6 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
-#pragma warning disable 618
-
 using System;
 using System.IO;
 using System.Linq;
@@ -35,6 +33,7 @@ sealed class RollingFileSink : ILogEventSink, IFlushableFileSink, IDisposable
         readonly bool _buffered;
         readonly bool _shared;
         readonly bool _rollOnFileSizeLimit;
+        readonly FileLifecycleHooks _hooks;
 
         readonly object _syncRoot = new object();
         bool _isDisposed;
@@ -50,11 +49,12 @@ public RollingFileSink(string path,
                               bool buffered,
                               bool shared,
                               RollingInterval rollingInterval,
-                              bool rollOnFileSizeLimit)
+                              bool rollOnFileSizeLimit,
+                              FileLifecycleHooks hooks)
         {
             if (path == null) throw new ArgumentNullException(nameof(path));
-            if (fileSizeLimitBytes.HasValue && fileSizeLimitBytes < 0) throw new ArgumentException("Negative value provided; file size limit must be non-negative");
-            if (retainedFileCountLimit.HasValue && retainedFileCountLimit < 1) throw new ArgumentException("Zero or negative value provided; retained file count limit must be at least 1");
+            if (fileSizeLimitBytes.HasValue && fileSizeLimitBytes < 0) throw new ArgumentException("Negative value provided; file size limit must be non-negative.");
+            if (retainedFileCountLimit.HasValue && retainedFileCountLimit < 1) throw new ArgumentException("Zero or negative value provided; retained file count limit must be at least 1.");
 
             _roller = new PathRoller(path, rollingInterval);
             _textFormatter = textFormatter;
@@ -64,6 +64,7 @@ public RollingFileSink(string path,
             _buffered = buffered;
             _shared = shared;
             _rollOnFileSizeLimit = rollOnFileSizeLimit;
+            _hooks = hooks;
         }
 
         public void Emit(LogEvent logEvent)
@@ -117,8 +118,11 @@ void OpenFile(DateTime now, int? minSequence = null)
             var existingFiles = Enumerable.Empty<string>();
             try
             {
-                existingFiles = Directory.GetFiles(_roller.LogFileDirectory, _roller.DirectorySearchPattern)
+                if (Directory.Exists(_roller.LogFileDirectory))
+                {
+                    existingFiles = Directory.GetFiles(_roller.LogFileDirectory, _roller.DirectorySearchPattern)
                                          .Select(Path.GetFileName);
+                }
             }
             catch (DirectoryNotFoundException) { }
 
@@ -143,8 +147,11 @@ void OpenFile(DateTime now, int? minSequence = null)
                 try
                 {
                     _currentFile = _shared ?
+#pragma warning disable 618
                         (IFileSink)new SharedFileSink(path, _textFormatter, _fileSizeLimitBytes, _encoding) :
-                        new FileSink(path, _textFormatter, _fileSizeLimitBytes, _encoding, _buffered);
+#pragma warning restore 618
+                        new FileSink(path, _textFormatter, _fileSizeLimitBytes, _encoding, _buffered, _hooks);
+
                     _currentFileSequence = sequence;
                 }
                 catch (IOException ex)

src/Serilog.Sinks.File/Sinks/File/SharedFileSink.AtomicAppend.cs

@@ -18,7 +18,6 @@
 using System.IO;
 using System.Security.AccessControl;
 using System.Text;
-using Serilog.Core;
 using Serilog.Events;
 using Serilog.Formatting;
 
@@ -51,17 +50,14 @@ public sealed class SharedFileSink : IFileSink, IDisposable
         /// will be written in full even if it exceeds the limit.</param>
         /// <param name="encoding">Character encoding used to write the text file. The default is UTF-8 without BOM.</param>
         /// <returns>Configuration object allowing method chaining.</returns>
-        /// <remarks>The file will be written using the UTF-8 character set.</remarks>
         /// <exception cref="IOException"></exception>
         public SharedFileSink(string path, ITextFormatter textFormatter, long? fileSizeLimitBytes, Encoding encoding = null)
         {
-            if (path == null) throw new ArgumentNullException(nameof(path));
-            if (textFormatter == null) throw new ArgumentNullException(nameof(textFormatter));
             if (fileSizeLimitBytes.HasValue && fileSizeLimitBytes < 0)
                 throw new ArgumentException("Negative value provided; file size limit must be non-negative");
 
-            _path = path;
-            _textFormatter = textFormatter;
+            _path = path ?? throw new ArgumentNullException(nameof(path));
+            _textFormatter = textFormatter ?? throw new ArgumentNullException(nameof(textFormatter));
             _fileSizeLimitBytes = fileSizeLimitBytes;
 
             var directory = Path.GetDirectoryName(path);

test/Serilog.Sinks.File.Tests/FileLoggerConfigurationExtensionsTests.cs

@@ -1,4 +1,4 @@
-using System;
+using System;
 using System.Threading;
 using Serilog.Sinks.File.Tests.Support;
 using Serilog.Tests.Support;
@@ -80,11 +80,11 @@ public void WhenFlushingToDiskReportedSharedFileSinkCanBeCreatedAndDisposed()
         }
 
         [Fact]
-        public void BufferingIsNotAvailableWhenSharingEnabled()
+        public void HooksAreNotAvailableWhenSharingEnabled()
         {
             Assert.Throws<ArgumentException>(() =>
                 new LoggerConfiguration()
-                    .WriteTo.File("logs", buffered: true, shared: true));
+                    .WriteTo.File("logs", shared: true, hooks: new GZipHooks()));
         }
     }
 }