Merge pull request #80 from cocowalla/feature/stream-wrapper

`FileLifecycleHooks`

Author: nblumhardt

.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.*

README.md

@@ -1,4 +1,4 @@
-# Serilog.Sinks.File [![Build status](https://ci.appveyor.com/api/projects/status/hh9gymy0n6tne46j?svg=true)](https://ci.appveyor.com/project/serilog/serilog-sinks-file) [![Travis build](https://travis-ci.org/serilog/serilog-sinks-file.svg)](https://travis-ci.org/serilog/serilog-sinks-file) [![NuGet Version](http://img.shields.io/nuget/v/Serilog.Sinks.File.svg?style=flat)](https://www.nuget.org/packages/Serilog.Sinks.File/) [![Documentation](https://img.shields.io/badge/docs-wiki-yellow.svg)](https://github.com/serilog/serilog/wiki) [![Join the chat at https://gitter.im/serilog/serilog](https://img.shields.io/gitter/room/serilog/serilog.svg)](https://gitter.im/serilog/serilog)
+# Serilog.Sinks.File [![Build status](https://ci.appveyor.com/api/projects/status/hh9gymy0n6tne46j?svg=true)](https://ci.appveyor.com/project/serilog/serilog-sinks-file) [![NuGet Version](http://img.shields.io/nuget/v/Serilog.Sinks.File.svg?style=flat)](https://www.nuget.org/packages/Serilog.Sinks.File/) [![Documentation](https://img.shields.io/badge/docs-wiki-yellow.svg)](https://github.com/serilog/serilog/wiki) [![Join the chat at https://gitter.im/serilog/serilog](https://img.shields.io/gitter/room/serilog/serilog.svg)](https://gitter.im/serilog/serilog)
 
 Writes [Serilog](https://serilog.net) events to one or more text files.
 

appveyor.yml

@@ -1,11 +1,18 @@
 version: '{build}'
 skip_tags: true
-image: Visual Studio 2017
+image:
+  - Visual Studio 2017
+  - Ubuntu
 configuration: Release
-install:
-  - ps: mkdir -Force ".\build\" | Out-Null
 build_script:
 - ps: ./Build.ps1
+for:
+-
+  matrix:
+    only:
+      - image: Ubuntu
+  build_script:
+    - sh build.sh
 test: off
 artifacts:
 - path: artifacts/Serilog.*.nupkg

build.sh

@@ -1,11 +1,17 @@
-#!/bin/bash
+#!/bin/bash
+
+set -e 
 dotnet --info
+dotnet --list-sdks
 dotnet restore
 
+echo "🤖 Attempting to build..."
 for path in src/**/*.csproj; do
-    dotnet build -f netstandard1.3 -c Release ${path} -p:EnableSourceLink=true
+    dotnet build -f netstandard1.3 -c Release ${path}
+    dotnet build -f netstandard2.0 -c Release ${path}
 done
 
+echo "🤖 Running tests..."
 for path in test/*.Tests/*.csproj; do
     dotnet test -f netcoreapp2.0  -c Release ${path}
 done

serilog-sinks-file.sln

@@ -8,7 +8,6 @@ EndProject
 Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "assets", "assets", "{E9D1B5E1-DEB9-4A04-8BAB-24EC7240ADAF}"
 	ProjectSection(SolutionItems) = preProject
 		.editorconfig = .editorconfig
-		.travis.yml = .travis.yml
 		appveyor.yml = appveyor.yml
 		Build.ps1 = Build.ps1
 		build.sh = build.sh

src/Serilog.Sinks.File/FileLoggerConfigurationExtensions.cs

@@ -0,0 +1,39 @@
+// 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;
+using System.Text;
+
+namespace Serilog.Sinks.File
+{
+    /// <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>
+        /// <param name="encoding">The encoding to use when reading/writing to the stream.</param>
+        /// <returns>The <see cref="Stream"/> Serilog should use when writing events to the log file.</returns>
+        public virtual Stream OnFileOpened(Stream underlyingStream, Encoding encoding) => underlyingStream;
+    }
+}

src/Serilog.Sinks.File/Sinks/File/FileLifecycleHooks.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,7 +78,16 @@ public FileSink(string path, ITextFormatter textFormatter, long? fileSizeLimitBy
                 outputStream = _countingStreamWrapper = new WriteCountingStream(_underlyingStream);
             }
 
-            _output = new StreamWriter(outputStream, encoding ?? new UTF8Encoding(encoderShouldEmitUTF8Identifier: false));
+            // Parameter reassignment.
+            encoding = encoding ?? new UTF8Encoding(encoderShouldEmitUTF8Identifier: false);
+
+            if (hooks != null)
+            {
+                outputStream = hooks.OnFileOpened(outputStream, encoding) ??
+                               throw new InvalidOperationException($"The file lifecycle hook `{nameof(FileLifecycleHooks.OnFileOpened)}(...)` returned `null`.");
+            }
+
+            _output = new StreamWriter(outputStream, encoding);
         }
 
         bool IFileSink.EmitOrOverflow(LogEvent logEvent)

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

@@ -1,4 +1,18 @@
-using System;
+// Copyright 2016-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;
 using System.Threading;
 using Serilog.Core;
 using Serilog.Debugging;
@@ -9,6 +23,7 @@ namespace Serilog.Sinks.File
     /// <summary>
     /// A sink wrapper that periodically flushes the wrapped sink to disk.
     /// </summary>
+    [Obsolete("This type will be removed from the public API in a future version; use `WriteTo.File(flushToDiskInterval:)` instead.")]
     public class PeriodicFlushToDiskSink : ILogEventSink, IDisposable
     {
         readonly ILogEventSink _sink;
@@ -21,15 +36,12 @@ public class PeriodicFlushToDiskSink : ILogEventSink, IDisposable
         /// </summary>
         /// <param name="sink">The sink to wrap.</param>
         /// <param name="flushInterval">The interval at which to flush the underlying sink.</param>
-        /// <exception cref="ArgumentNullException"></exception>
+        /// <exception cref="ArgumentNullException"/>
         public PeriodicFlushToDiskSink(ILogEventSink sink, TimeSpan flushInterval)
         {
-            if (sink == null) throw new ArgumentNullException(nameof(sink));
-
-            _sink = sink;
+            _sink = sink ?? throw new ArgumentNullException(nameof(sink));
 
-            var flushable = sink as IFlushableFileSink;
-            if (flushable != null)
+            if (sink is IFlushableFileSink flushable)
             {
                 _timer = new Timer(_ => FlushToDisk(flushable), null, flushInterval, flushInterval);
             }

src/Serilog.Sinks.File/Sinks/File/PeriodicFlushToDiskSink.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)
@@ -146,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/RollingFileSink.cs

@@ -1,4 +1,4 @@
-// Copyright 2013-2016 Serilog Contributors
+// Copyright 2013-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.
@@ -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);

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

@@ -1,4 +1,4 @@
-// Copyright 2013-2016 Serilog Contributors
+// Copyright 2013-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.
@@ -17,7 +17,6 @@
 using System;
 using System.IO;
 using System.Text;
-using Serilog.Core;
 using Serilog.Events;
 using Serilog.Formatting;
 using System.Threading;
@@ -28,6 +27,7 @@ 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(shared: true)` instead.")]
     public sealed class SharedFileSink : IFileSink, IDisposable
     {
         readonly TextWriter _output;
@@ -53,11 +53,9 @@ public sealed class SharedFileSink : IFileSink, IDisposable
         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");
-
-            _textFormatter = textFormatter;
+            _textFormatter = textFormatter ?? throw new ArgumentNullException(nameof(textFormatter));
             _fileSizeLimitBytes = fileSizeLimitBytes;
 
             var directory = Path.GetDirectoryName(path);

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

@@ -1,4 +1,4 @@
-// Copyright 2013-2016 Serilog Contributors
+// Copyright 2013-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.
@@ -20,16 +20,14 @@ namespace Serilog.Sinks.File
     sealed class WriteCountingStream : Stream
     {
         readonly Stream _stream;
-        long _countedLength;
 
         public WriteCountingStream(Stream stream)
         {
-            if (stream == null) throw new ArgumentNullException(nameof(stream));
-            _stream = stream;
-            _countedLength = stream.Length;
+            _stream = stream ?? throw new ArgumentNullException(nameof(stream));
+            CountedLength = stream.Length;
         }
 
-        public long CountedLength => _countedLength;
+        public long CountedLength { get; private set; }
 
         protected override void Dispose(bool disposing)
         {
@@ -42,7 +40,7 @@ protected override void Dispose(bool disposing)
         public override void Write(byte[] buffer, int offset, int count)
         {
             _stream.Write(buffer, offset, count);
-            _countedLength += count;
+            CountedLength += count;
         }
 
         public override void Flush() => _stream.Flush();
@@ -54,8 +52,8 @@ public override void Write(byte[] buffer, int offset, int count)
 
         public override long Position
         {
-            get { return _stream.Position; }
-            set { throw new NotSupportedException(); }
+            get => _stream.Position;
+            set => throw new NotSupportedException();
         }
 
         public override long Seek(long offset, SeekOrigin origin)
@@ -73,4 +71,4 @@ public override int Read(byte[] buffer, int offset, int count)
             throw new NotSupportedException();
         }
     }
-}
+}