Clean-up and documentation

seq-api.sln.DotSettings

@@ -1,11 +1,16 @@
 <wpf:ResourceDictionary xml:space="preserve" xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml" xmlns:s="clr-namespace:System;assembly=mscorlib" xmlns:ss="urn:shemas-jetbrains-com:settings-storage-xaml" xmlns:wpf="http://schemas.microsoft.com/winfx/2006/xaml/presentation">
 	<s:String x:Key="/Default/CodeStyle/Naming/CSharpNaming/Abbreviations/=AD/@EntryIndexedValue">AD</s:String>
 	<s:Boolean x:Key="/Default/UserDictionary/Words/=apikey/@EntryIndexedValue">True</s:Boolean>
+	<s:Boolean x:Key="/Default/UserDictionary/Words/=Datalust/@EntryIndexedValue">True</s:Boolean>
 	<s:Boolean x:Key="/Default/UserDictionary/Words/=dstkey/@EntryIndexedValue">True</s:Boolean>
+	<s:Boolean x:Key="/Default/UserDictionary/Words/=hrefs/@EntryIndexedValue">True</s:Boolean>
+	<s:Boolean x:Key="/Default/UserDictionary/Words/=Parameterize/@EntryIndexedValue">True</s:Boolean>
 	<s:Boolean x:Key="/Default/UserDictionary/Words/=permalinked/@EntryIndexedValue">True</s:Boolean>
 	<s:Boolean x:Key="/Default/UserDictionary/Words/=permalinks/@EntryIndexedValue">True</s:Boolean>
 	<s:Boolean x:Key="/Default/UserDictionary/Words/=Permalinks/@EntryIndexedValue">True</s:Boolean>
 	<s:Boolean x:Key="/Default/UserDictionary/Words/=Reentrant/@EntryIndexedValue">True</s:Boolean>
+	<s:Boolean x:Key="/Default/UserDictionary/Words/=Serilog/@EntryIndexedValue">True</s:Boolean>
 	<s:Boolean x:Key="/Default/UserDictionary/Words/=srckey/@EntryIndexedValue">True</s:Boolean>
+	<s:Boolean x:Key="/Default/UserDictionary/Words/=Unsubscriber/@EntryIndexedValue">True</s:Boolean>
 	<s:Boolean x:Key="/Default/UserDictionary/Words/=Workspaces/@EntryIndexedValue">True</s:Boolean>
 </wpf:ResourceDictionary>

src/Seq.Api/Client/SeqApiException.cs

@@ -1,4 +1,18 @@
-using System;
+// Copyright 2014-2019 Datalust and 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.Net;
 
 namespace Seq.Api.Client

src/Seq.Api/Model/Entity.cs

@@ -1,14 +1,42 @@
-namespace Seq.Api.Model
+// Copyright 2014-2019 Datalust and 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.
+
+namespace Seq.Api.Model
 {
+    /// <summary>
+    /// A uniquely-identifiable resource available from the Seq HTTP API.
+    /// </summary>
     public abstract class Entity : ILinked
     {
+        /// <summary>
+        /// Construct an <see cref="Entity"/>.
+        /// </summary>
         protected Entity()
         {
             Links = new LinkCollection();
         }
 
+        /// <summary>
+        /// The entity's unique identifier. This will be <c>null</c> if a newly-instantiated <see cref="Entity"/>
+        /// has not yet been sent to the server.
+        /// </summary>
         public string Id { get; set; }
 
+        /// <summary>
+        /// A collection of outbound links from the entity. This will be empty if the entity
+        /// was instantiated locally and not received from the API.
+        /// </summary>
         public LinkCollection Links { get; set; }
     }
 }

src/Seq.Api/Model/ILinked.cs

@@ -1,7 +1,27 @@
-namespace Seq.Api.Model
+// Copyright 2014-2019 Datalust and 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.
+
+namespace Seq.Api.Model
 {
+    /// <summary>
+    /// A resource that carries outbound links.
+    /// </summary>
     public interface ILinked
     {
+        /// <summary>
+        /// Links associated with the resource.
+        /// </summary>
         LinkCollection Links { get; }
     }
 }

src/Seq.Api/Model/Link.cs

@@ -1,50 +1,81 @@
-using System;
+// Copyright 2014-2019 Datalust and 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.Collections.Generic;
 using System.Linq;
-using System.Reflection;
 using Tavis.UriTemplates;
 
+// ReSharper disable PossibleMultipleEnumeration
+
 namespace Seq.Api.Model
 {
-    public class Link
+    /// <summary>
+    /// A hypermedia link. A link is an RFC 6570 URI template that can be
+    /// parameterized in order to produce a complete URI (if the template contains no
+    /// parameters then it may also be a literal URI).
+    /// </summary>
+    public struct Link
     {
-        readonly bool _isLiteral;
-        readonly string _href;
-        readonly IDictionary<string, object> _parameters;
-
-        public Link(string href, bool isLiteral = true)
-            : this(href, new Dictionary<string, object>())
-        {
-            _isLiteral = isLiteral;
-        }
+        /// <summary>
+        /// An empty link.
+        /// </summary>
+        public static Link Empty { get; } = default;
 
-        public Link(string href, IDictionary<string, object> parameters)
+        /// <summary>
+        /// Construct a link.
+        /// </summary>
+        /// <param name="template">The URI template.</param>
+        public Link(string template)
         {
-            if (href == null) throw new ArgumentNullException(nameof(href));
-            if (parameters == null) throw new ArgumentNullException(nameof(parameters));
-            _href = href;
-            _parameters = parameters;
+            Template = template ?? throw new ArgumentNullException(nameof(template));
         }
 
-        public Link(string href, object parameters)
-            : this(href, parameters
-                .GetType()
-                .GetTypeInfo()
-                .DeclaredProperties
-                .ToDictionary(p => p.Name, p => p.GetValue(parameters)))
-        {
-        }
+        /// <summary>
+        /// Get the unprocessed URI template.
+        /// </summary>
+        public string Template { get; }
 
-        public string GetUri()
+        /// <summary>
+        /// Parameterize the link to construct a URI.
+        /// </summary>
+        /// <param name="parameters">Parameters to substitute into the template, if any.</param>
+        /// <returns>A constructed URI.</returns>
+        /// <remarks>This method ensures that templates containing parameters cannot be accidentally
+        /// used as URIs.</remarks>
+        public string GetUri(IDictionary<string, object> parameters = null)
         {
-            if (_isLiteral) return _href;
+            if (Template == null) throw new InvalidOperationException("Attempted to process an empty URI template.");
 
-            var template = new UriTemplate(_href);
-            foreach (var parameter in _parameters)
+            var template = new UriTemplate(Template);
+            if (parameters != null)
             {
-                template.SetParameter(parameter.Key, parameter.Value);
+                var missing = parameters.Select(p => p.Key).Except(template.GetParameterNames());
+                if (missing.Any())
+                    throw new ArgumentException($"The URI template `{Template}` does not contain parameter: `{string.Join("`, `", missing)}`.");
+
+                foreach (var parameter in parameters)
+                {
+                    var value = parameter.Value is DateTime time
+                        ? time.ToString("O")
+                        : parameter.Value;
+
+                    template.SetParameter(parameter.Key, value);
+                }
             }
+
             return template.Resolve();
         }
     }
-}
+}

src/Seq.Api/Model/LinkCollection.cs

@@ -1,18 +1,30 @@
-using System;
+// Copyright 2014-2019 Datalust and 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.Collections.Generic;
 using Newtonsoft.Json;
 using Seq.Api.Serialization;
 
 namespace Seq.Api.Model
 {
+    /// <summary>
+    /// A collection of <see cref="Link"/>s indexed by case-insensitive name.
+    /// </summary>
     [JsonConverter(typeof(LinkCollectionConverter))]
     public class LinkCollection : Dictionary<string, Link>
     {
         public LinkCollection() : base(StringComparer.OrdinalIgnoreCase) { }
-
-        public string GetUri(string name)
-        {
-            return this[name].GetUri();
-        }
     }
 }

src/Seq.Api/Model/ResourceGroup.cs

@@ -1,12 +1,34 @@
-namespace Seq.Api.Model
+// Copyright 2014-2019 Datalust and 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.
+
+namespace Seq.Api.Model
 {
+    /// <summary>
+    /// A resource group is a logical partitioning of the API, usually
+    /// associated with a particular type of entity.
+    /// </summary>
     public class ResourceGroup : ILinked
     {
+        /// <summary>
+        /// Construct a <see cref="ResourceGroup"/>.
+        /// </summary>
         public ResourceGroup()
         {
             Links = new LinkCollection();
         }
 
+        /// <inheritdoc/>
         public LinkCollection Links { get; set; }
     }
 }

src/Seq.Api/SeqConnection.cs

@@ -1,4 +1,18 @@
-using System;
+// Copyright 2014-2019 Datalust and 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.Collections.Generic;
 using System.Net;
 using System.Threading;

src/Seq.Api/Serialization/LinkCollectionConverter.cs

@@ -1,17 +1,31 @@
-using System;
+// Copyright 2014-2019 Datalust and 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.Collections.Generic;
 using System.Linq;
 using Newtonsoft.Json;
 using Seq.Api.Model;
 
 namespace Seq.Api.Serialization
 {
-    public class LinkCollectionConverter : JsonConverter
+    class LinkCollectionConverter : JsonConverter
     {
         public override void WriteJson(JsonWriter writer, object value, JsonSerializer serializer)
         {
             var lc = (LinkCollection)value;
-            var dictionary = lc.ToDictionary(kv => kv.Key, kv => kv.Value.GetUri());
+            var dictionary = lc.ToDictionary(kv => kv.Key, kv => kv.Value.Template);
             serializer.Serialize(writer, dictionary);
         }
 

src/Seq.Api/Streams/ObservableStream.Unsubscriber.cs

@@ -12,6 +12,7 @@
 // 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;
 
 namespace Seq.Api.Streams
@@ -25,10 +26,8 @@ sealed class Unsubscriber : IDisposable
 
             public Unsubscriber(ObservableStream<T> sink, IObserver<T> observer)
             {
-                if (sink == null) throw new ArgumentNullException(nameof(sink));
-                if (observer == null) throw new ArgumentNullException(nameof(observer));
-                _stream = sink;
-                _observer = observer;
+                _stream = sink ?? throw new ArgumentNullException(nameof(sink));
+                _observer = observer ?? throw new ArgumentNullException(nameof(observer));
             }
 
             public void Dispose()