Merge branch 'release/5.0.0'

Author: Jericho

README.md

@@ -81,7 +81,7 @@ The parser was built for and tested on NET 4.6.1, NET 4,7,2 and NETSTANDARD 2.0.
     // ==== Advanced Parsing ====
     var parser = new StreamingMultipartFormDataParser(stream);
     parser.ParameterHandler += parameter => DoSomethingWithParameter(parameter);
-    parser.FileHandler += (name, fileName, type, disposition, buffer, bytes, partNumber) =>
+    parser.FileHandler += (name, fileName, type, disposition, buffer, bytes, partNumber, additionalProperties) =>
     {
         // Write the part of the file we've received to a file stream. (Or do something else)
         filestream.Write(buffer, 0, bytes);
@@ -154,7 +154,7 @@ The parser was built for and tested on NET 4.6.1, NET 4,7,2 and NETSTANDARD 2.0.
     // ==== Advanced Parsing ====
     var parser = new StreamingMultipartFormDataParser(stream);
     parser.ParameterHandler += parameter => DoSomethingWithParameter(parameter);
-    parser.FileHandler += (name, fileName, type, disposition, buffer, bytes, partNumber) =>
+    parser.FileHandler += (name, fileName, type, disposition, buffer, bytes, partNumber, additionalProperties) =>
     {
         // Write the part of the file we've received to a file stream. (Or do something else)
         // Assume that filesreamsByName is a Dictionary<string, FileStream> of all the files

Source/HttpMultipartParser.UnitTests/ParserScenarios/FileWithAdditionalParameter.cs

@@ -0,0 +1,64 @@
+using System.Collections.Generic;
+using System.IO;
+using System.Linq;
+using System.Text;
+using System.Threading.Tasks;
+using Xunit;
+
+namespace HttpMultipartParser.UnitTests.ParserScenarios
+{
+    public class FileWithAdditionalParameter
+    {
+        private static readonly string _testData = TestUtil.TrimAllLines(
+            @"-----------------------------41952539122868
+            Content-ID: <some string>
+            Content-Type: application/octet-stream
+
+            <... binary data ...>
+            -----------------------------41952539122868--"
+        );
+
+        /// <summary>
+        ///     Test case for files with additional parameter.
+        /// </summary>
+        private static readonly TestData _testCase = new TestData(
+            _testData,
+            new List<ParameterPart> { },
+            new List<FilePart> {
+                new FilePart(null, null, TestUtil.StringToStreamNoBom("<... binary data ...>"), (new[] { new KeyValuePair<string, string>("content-id", "<some string>") }).ToDictionary(kvp => kvp.Key, kvp => kvp.Value), "application/octet-stream", "form-data")
+            }
+       );
+
+        /// <summary>
+        ///     Initializes the test data before each run, this primarily
+        ///     consists of resetting data stream positions.
+        /// </summary>
+        public FileWithAdditionalParameter()
+        {
+            foreach (var filePart in _testCase.ExpectedFileData)
+            {
+                filePart.Data.Position = 0;
+            }
+        }
+
+        [Fact]
+        public void FileWithAdditionalParameterTest()
+        {
+            using (Stream stream = TestUtil.StringToStream(_testCase.Request, Encoding.UTF8))
+            {
+                var parser = MultipartFormDataParser.Parse(stream, Encoding.UTF8);
+                Assert.True(_testCase.Validate(parser));
+            }
+        }
+
+        [Fact]
+        public async Task FileWithAdditionalParameterTest_Async()
+        {
+            using (Stream stream = TestUtil.StringToStream(_testCase.Request, Encoding.UTF8))
+            {
+                var parser = await MultipartFormDataParser.ParseAsync(stream, Encoding.UTF8).ConfigureAwait(false);
+                Assert.True(_testCase.Validate(parser));
+            }
+        }
+    }
+}

Source/HttpMultipartParser.UnitTests/ParserScenarios/TestData.cs

@@ -112,6 +112,9 @@ private bool ValidateFiles(MultipartFormDataParser parser)
                 if (expectedFile.ContentType != actualFile.ContentType) return false;
                 if (expectedFile.ContentDisposition != actualFile.ContentDisposition) return false;
 
+                if (expectedFile.AdditionalProperties.Count != actualFile.AdditionalProperties.Count) return false;
+                if (expectedFile.AdditionalProperties.Except(actualFile.AdditionalProperties).Any()) return false;
+
                 // Read the data from the files and see if it's the same
                 if (expectedFile.Data.CanSeek && expectedFile.Data.Position != 0) expectedFile.Data.Position = 0;
                 if (actualFile.Data.CanSeek && actualFile.Data.Position != 0) actualFile.Data.Position = 0;

Source/HttpMultipartParser/Extensions.cs

@@ -0,0 +1,50 @@
+using System.Collections.Generic;
+using System.Linq;
+
+namespace HttpMultipartParser
+{
+    /// <summary>
+    /// Class containing various extension methods.
+    /// </summary>
+    public static class Extensions
+    {
+        /// <summary>
+        /// Returns true if the parameter has any values. False otherwise.
+        /// </summary>
+        /// <param name="parser">The multipart form parser.</param>
+        /// <param name="name">The name of the parameter.</param>
+        /// <returns>True if the parameter exists. False otherwise.</returns>
+        public static bool HasParameter(this IMultipartFormDataParser parser, string name)
+        {
+            return parser.Parameters.Any(p => p.Name == name);
+        }
+
+        /// <summary>
+        /// Returns the value of a parameter or null if it doesn't exist.
+        ///
+        /// You should only use this method if you're sure the parameter has only one value.
+        ///
+        /// If you need to support multiple values use GetParameterValues.
+        /// </summary>
+        /// <param name="parser">The multipart form parser.</param>
+        /// <param name="name">The name of the parameter.</param>
+        /// <returns>The value of the parameter.</returns>
+        public static string GetParameterValue(this IMultipartFormDataParser parser, string name)
+        {
+            return parser.GetParameterValues(name).FirstOrDefault();
+        }
+
+        /// <summary>
+        /// Returns the values of a parameter or an empty enumerable if the parameter doesn't exist.
+        /// </summary>
+        /// <param name="parser">The multipart form parser.</param>
+        /// <param name="name">The name of the parameter.</param>
+        /// <returns>The values of the parameter.</returns>
+        public static IEnumerable<string> GetParameterValues(this IMultipartFormDataParser parser, string name)
+        {
+            return parser.Parameters
+                .Where(p => p.Name == name)
+                .Select(p => p.Data);
+        }
+    }
+}

Source/HttpMultipartParser/FilePart.cs

@@ -24,6 +24,8 @@
 // </summary>
 // --------------------------------------------------------------------------------------------------------------------
 
+using System.Collections.Generic;
+using System.Collections.ObjectModel;
 using System.IO;
 using System.Linq;
 
@@ -35,6 +37,13 @@ namespace HttpMultipartParser
     /// </summary>
     public class FilePart
     {
+        #region Fields
+
+        private const string DefaultContentType = "text/plain";
+        private const string DontentDisposition = "form-data";
+
+        #endregion
+
         #region Constructors and Destructors
 
         /// <summary>
@@ -49,8 +58,14 @@ public class FilePart
         /// <param name="data">
         ///     The file data.
         /// </param>
-        public FilePart(string name, string fileName, Stream data)
-            : this(name, fileName, data, "text/plain", "form-data")
+        /// <param name="contentType">
+        ///     The content type.
+        /// </param>
+        /// <param name="contentDisposition">
+        ///     The content disposition.
+        /// </param>
+        public FilePart(string name, string fileName, Stream data, string contentType = DefaultContentType, string contentDisposition = DontentDisposition)
+            : this(name, fileName, data, null, contentType, contentDisposition)
         {
         }
 
@@ -66,19 +81,23 @@ public FilePart(string name, string fileName, Stream data)
         /// <param name="data">
         ///     The file data.
         /// </param>
+        /// <param name="additionalProperties">
+        ///     Additional properties associated with this file.
+        /// </param>
         /// <param name="contentType">
         ///     The content type.
         /// </param>
         /// <param name="contentDisposition">
         ///     The content disposition.
         /// </param>
-        public FilePart(string name, string fileName, Stream data, string contentType, string contentDisposition)
+        public FilePart(string name, string fileName, Stream data, IDictionary<string, string> additionalProperties, string contentType = DefaultContentType, string contentDisposition = DontentDisposition)
         {
             Name = name;
             FileName = fileName?.Split(Path.GetInvalidFileNameChars()).Last();
             Data = data;
             ContentType = contentType;
             ContentDisposition = contentDisposition;
+            AdditionalProperties = new ReadOnlyDictionary<string, string>(additionalProperties ?? new Dictionary<string, string>());
         }
 
         #endregion
@@ -88,27 +107,33 @@ public FilePart(string name, string fileName, Stream data, string contentType, s
         /// <summary>
         ///     Gets the data.
         /// </summary>
-        public Stream Data { get; private set; }
+        public Stream Data { get; }
+
+        /// <summary>
+        ///     Gets the file name.
+        /// </summary>
+        public string FileName { get; }
 
         /// <summary>
-        ///     Gets or sets the file name.
+        ///     Gets the name.
         /// </summary>
-        public string FileName { get; set; }
+        public string Name { get; }
 
         /// <summary>
-        ///     Gets or sets the name.
+        ///     Gets the content-type. Defaults to text/plain if unspecified.
         /// </summary>
-        public string Name { get; set; }
+        public string ContentType { get; }
 
         /// <summary>
-        ///     Gets or sets the content-type. Defaults to text/plain if unspecified.
+        ///     Gets the content-disposition. Defaults to form-data if unspecified.
         /// </summary>
-        public string ContentType { get; set; }
+        public string ContentDisposition { get; }
 
         /// <summary>
-        ///     Gets or sets the content-disposition. Defaults to form-data if unspecified.
+        /// Gets the additional properties associated with this file.
+        /// An additional property is any property other than the "well known" ones such as name, filename, content-type, etc.
         /// </summary>
-        public string ContentDisposition { get; set; }
+        public IReadOnlyDictionary<string, string> AdditionalProperties { get; private set; }
 
         #endregion
     }

Source/HttpMultipartParser/IMultipartFormDataParser.cs

@@ -0,0 +1,25 @@
+using System.Collections.Generic;
+
+namespace HttpMultipartParser
+{
+    /// <summary>
+    ///     Provides methods to parse a
+    ///     <see href="http://www.ietf.org/rfc/rfc2388.txt">
+    ///         <c>multipart/form-data</c>
+    ///     </see>
+    ///     stream into it's parameters and file data.
+    /// </summary>
+    public interface IMultipartFormDataParser
+    {
+        /// <summary>
+        ///     Gets the mapping of parameters parsed files. The name of a given field
+        ///     maps to the parsed file data.
+        /// </summary>
+        IReadOnlyList<FilePart> Files { get; }
+
+        /// <summary>
+        ///     Gets the parameters. Several ParameterParts may share the same name.
+        /// </summary>
+        IReadOnlyList<ParameterPart> Parameters { get; }
+    }
+}

Source/HttpMultipartParser/IStreamingMultipartFormDataParser.cs

@@ -0,0 +1,70 @@
+using System.Collections.Generic;
+using System.Threading;
+using System.Threading.Tasks;
+
+namespace HttpMultipartParser
+{
+    /// <summary>
+    /// The FileStreamDelegate defining functions that can handle file stream data from this parser.
+    ///
+    /// Delegates can assume that the data is sequential i.e. the data received by any delegates will be
+    /// the data immediately following any previously received data.
+    /// </summary>
+    /// <param name="name">The name of the multipart data.</param>
+    /// <param name="fileName">The name of the file.</param>
+    /// <param name="contentType">The content type of the multipart data.</param>
+    /// <param name="contentDisposition">The content disposition of the multipart data.</param>
+    /// <param name="buffer">Some of the data from the file (not necessarily all of the data).</param>
+    /// <param name="bytes">The length of data in buffer.</param>
+    /// <param name="partNumber">Each chunk (or "part") in a given file is sequentially numbered, starting at zero.</param>
+    /// <param name="additionalProperties">Properties other than the "well known" ones (such as name, filename, content-type, etc.) associated with a file stream.</param>
+    public delegate void FileStreamDelegate(string name, string fileName, string contentType, string contentDisposition, byte[] buffer, int bytes, int partNumber, IDictionary<string, string> additionalProperties);
+
+    /// <summary>
+    /// The StreamClosedDelegate defining functions that can handle stream being closed.
+    /// </summary>
+    public delegate void StreamClosedDelegate();
+
+    /// <summary>
+    /// The ParameterDelegate defining functions that can handle multipart parameter data.
+    /// </summary>
+    /// <param name="part">The parsed parameter part.</param>
+    public delegate void ParameterDelegate(ParameterPart part);
+
+    /// <summary>
+    ///     Provides methods to parse a
+    ///     <see href="http://www.ietf.org/rfc/rfc2388.txt">
+    ///         <c>multipart/form-data</c>
+    ///     </see>
+    ///     stream into it's parameters and file data.
+    /// </summary>
+    public interface IStreamingMultipartFormDataParser
+    {
+        /// <summary>
+        /// Gets or sets the FileHandler. Delegates attached to this property will receive sequential file stream data from this parser.
+        /// </summary>
+        FileStreamDelegate FileHandler { get; set; }
+
+        /// <summary>
+        /// Gets or sets the ParameterHandler. Delegates attached to this property will receive parameter data.
+        /// </summary>
+        ParameterDelegate ParameterHandler { get; set; }
+
+        /// <summary>
+        /// Gets or sets the StreamClosedHandler. Delegates attached to this property will be notified when the source stream is exhausted.
+        /// </summary>
+        StreamClosedDelegate StreamClosedHandler { get; set; }
+
+        /// <summary>
+        /// Execute the parser. This should be called after all handlers have been set.
+        /// </summary>
+        void Run();
+
+        /// <summary>
+        /// Execute the parser asynchronously. This should be called after all handlers have been set.
+        /// </summary>
+        /// <param name="cancellationToken">The cancellation token.</param>
+        /// <returns>The asynchronous task.</returns>
+        Task RunAsync(CancellationToken cancellationToken = default);
+    }
+}