Generate Documentation in Build

Dockerfile

@@ -5,6 +5,9 @@ ARG TRAVIS_COMMIT
 ARG TRAVIS_PULL_REQUEST
 ARG TRAVIS_BRANCH
 ARG MYGET_API_KEY
+
+RUN apk add nodejs yarn --no-cache
+
 WORKDIR /src
 
 COPY ./src/*.sln ./
@@ -17,6 +20,10 @@ RUN dotnet restore --runtime=alpine.3.7-x64
 
 COPY ./src .
 
+WORKDIR /docs
+
+COPY ./docs/package.json ./docs/yarn.lock ./
+
 WORKDIR /build
 
 COPY ./build/build.csproj .

build/Program.cs

@@ -1,5 +1,8 @@
 using System;
 using System.IO;
+using System.Linq;
+using System.Runtime.InteropServices;
+using System.Threading.Tasks;
 using static Bullseye.Targets;
 using static SimpleExec.Command;
 
@@ -8,6 +11,7 @@ static class Program
     private const string ArtifactsDir = "artifacts";
 
     private const string Clean = nameof(Clean);
+    private const string GenerateDocumentation = nameof(GenerateDocumentation);
     private const string Build = nameof(Build);
     private const string RunTests = nameof(RunTests);
     private const string Pack = nameof(Pack);
@@ -30,38 +34,73 @@ public static void Main(string[] args)
         });
 
         Target(
-            Build, 
+            GenerateDocumentation,
+            () =>
+            {
+                var srcDirectory = new DirectoryInfo("./src");
+
+                var schemaFiles = srcDirectory.GetFiles("*.schema.json", SearchOption.AllDirectories);
+
+                var schemaDirectories = schemaFiles
+                    .Select(schemaFile => schemaFile.DirectoryName)
+                    .Distinct()
+                    .Select(schemaDirectory =>
+                        schemaDirectory.Replace(Path.DirectorySeparatorChar,
+                            '/')); // normalize paths; yarn/node can handle forward slashes
+
+                if (RuntimeInformation.IsOSPlatform(OSPlatform.Windows))
+                {
+                    Run("cmd", "/c yarn", "docs");
+                }
+                else
+                {
+                    Run("yarn", string.Empty, "docs");
+                }
+
+                foreach (var schemaDirectory in schemaDirectories)
+                {
+                    Run(
+                        "node",
+                        $"node_modules/@adobe/jsonschema2md/cli.js -n --input {schemaDirectory} --out {schemaDirectory} --schema-out=-",
+                        "docs");
+                }
+            });
+
+        Target(
+            Build,
+            DependsOn(GenerateDocumentation),
             () => Run(
-                "dotnet", 
+                "dotnet",
                 $"build src/SqlStreamStore.HAL.sln -c Release /p:BuildMetadata={buildMetadata}"));
 
         Target(
             RunTests,
             DependsOn(Build),
             () => Run(
                 "dotnet",
-                $"test src/SqlStreamStore.HAL.Tests -c Release -r ../../{ArtifactsDir} --no-build -l trx;LogFileName=SqlStreamStore.HAL.Tests.xml"));
+                $"test src/SqlStreamStore.HAL.Tests -c Release -r ../../{ArtifactsDir} --verbosity normal --no-build -l trx;LogFileName=SqlStreamStore.HAL.Tests.xml"));
 
         Target(
             Pack,
-            DependsOn(Build), 
+            DependsOn(Build),
             () => Run(
                 "dotnet",
                 $"pack src/SqlStreamStore.HAL -c Release -o ../../{ArtifactsDir} --no-build"));
 
         Target(
-            Publish, 
-            DependsOn(Pack), 
-            () => {
+            Publish,
+            DependsOn(Pack),
+            () =>
+            {
                 var packagesToPush = Directory.GetFiles(ArtifactsDir, "*.nupkg", SearchOption.TopDirectoryOnly);
                 Console.WriteLine($"Found packages to publish: {string.Join("; ", packagesToPush)}");
-    
+
                 if (string.IsNullOrWhiteSpace(apiKey))
                 {
                     Console.WriteLine("MyGet API key not available. Packages will not be pushed.");
                     return;
                 }
-    
+
                 foreach (var packageToPush in packagesToPush)
                 {
                     Run(
@@ -77,15 +116,15 @@ public static void Main(string[] args)
 
     private static string GetBranch()
         => (Environment.GetEnvironmentVariable("TRAVIS_PULL_REQUEST")?.ToLower() == "false"
-                ? null
-                : $"pr-{Environment.GetEnvironmentVariable("TRAVIS_PULL_REQUEST")}")
-            ?? Environment.GetEnvironmentVariable("TRAVIS_BRANCH") 
-            ?? "none";
+               ? null
+               : $"pr-{Environment.GetEnvironmentVariable("TRAVIS_PULL_REQUEST")}")
+           ?? Environment.GetEnvironmentVariable("TRAVIS_BRANCH")
+           ?? "none";
 
-    private static string GetCommitHash() 
+    private static string GetCommitHash()
         => Environment.GetEnvironmentVariable("TRAVIS_PULL_REQUEST_SHA")
-            ?? Environment.GetEnvironmentVariable("TRAVIS_COMMIT")
-            ?? "none";
+           ?? Environment.GetEnvironmentVariable("TRAVIS_COMMIT")
+           ?? "none";
 
     private static string GetBuildNumber()
         => (Environment.GetEnvironmentVariable("TRAVIS_BUILD_NUMBER") ?? "0").PadLeft(5, '0');

src/SqlStreamStore.HAL.DevServer/WebHostBuilderExtensions.cs

@@ -7,7 +7,6 @@ internal static class WebHostBuilderExtensions
     {
         public static IWebHostBuilder UseStartup(this IWebHostBuilder builder, IStartup startup)
             => builder
-                .ConfigureServices(services => services.AddSingleton(startup))
-                .UseSetting(WebHostDefaults.ApplicationKey, startup.GetType().AssemblyQualifiedName);
+                .ConfigureServices(services => services.AddSingleton(startup));
     }
 }

src/SqlStreamStore.HAL.Tests/AllStreamMessageTests.cs

@@ -3,6 +3,7 @@ namespace SqlStreamStore.HAL.Tests
     using System;
     using System.Net;
     using System.Threading.Tasks;
+    using Microsoft.AspNetCore.Http;
     using Shouldly;
     using Xunit;
 
@@ -31,7 +32,7 @@ public async Task read_single_message_all_stream()
 
                 resource.ShouldLink(
                     Links
-                        .RootedAt("../")
+                        .FromRequestMessage(response.RequestMessage)
                         .Find()
                         .Index()
                         .AddSelf(Constants.Relations.Message, "stream/0")
@@ -49,7 +50,7 @@ public async Task read_single_message_does_not_exist_all_stream()
                 var resource = await response.AsHal();
 
                 resource.ShouldLink(Links
-                    .RootedAt("../")
+                    .FromPath(new PathString("/stream/0"))
                     .AddSelf(Constants.Relations.Message, "stream/0")
                     .Add(Constants.Relations.Feed, HeadOfAll));
             }

src/SqlStreamStore.HAL.Tests/StreamMessageTests.cs

@@ -31,7 +31,7 @@ public async Task read_single_message_stream()
                 var resource = await response.AsHal();
 
                 resource.ShouldLink(Links
-                    .RootedAt("../../")
+                    .FromRequestMessage(response.RequestMessage)
                     .Index()
                     .Find()
                     .Add(Constants.Relations.Self, "streams/a-stream/0")
@@ -54,7 +54,7 @@ public async Task read_single_message_does_not_exist_stream()
                 var resource = await response.AsHal();
 
                 resource.ShouldLink(Links
-                    .RootedAt("../../")
+                    .FromRequestMessage(response.RequestMessage)
                     .Index()
                     .Find()
                     .Add(Constants.Relations.Self, "streams/a-stream/0")

src/SqlStreamStore.HAL.Tests/StreamMetadataTests.cs

@@ -42,7 +42,7 @@ await _fixture.HttpClient.SendAsync(
 
                 resource.ShouldLink(
                     Links
-                        .RootedAt("../../../")
+                        .FromRequestMessage(response.RequestMessage)
                         .Index()
                         .Find()
                         .Add(Constants.Relations.Metadata, $"streams/{StreamId}/metadata").Self()
@@ -93,7 +93,7 @@ await _fixture.HttpClient.SendAsync(
 
                 resource.ShouldLink(
                     Links
-                        .RootedAt("../../../")
+                        .FromRequestMessage(response.RequestMessage)
                         .Index()
                         .Find()
                         .Add(Constants.Relations.Metadata, $"streams/{StreamId}/metadata").Self()
@@ -139,7 +139,7 @@ public async Task set_metadata()
 
                 resource.ShouldLink(
                     Links
-                        .RootedAt("../../../")
+                        .FromRequestMessage(response.RequestMessage)
                         .Index()
                         .Find()
                         .Add(Constants.Relations.Metadata, $"streams/{StreamId}/metadata").Self()

src/SqlStreamStore.HAL.Tests/StreamNavigationTests.cs

@@ -46,7 +46,7 @@ public async Task read_head_link_no_messages(string path, string root, HttpStatu
                 var resource = await response.AsHal();
 
                 var links = Links
-                    .RootedAt(root)
+                    .FromRequestMessage(response.RequestMessage)
                     .Index()
                     .Find()
                     .Add(Constants.Relations.Self, $"{path}?{LastLinkQuery}")
@@ -85,7 +85,7 @@ public async Task read_head_link_when_multiple_pages(string path, string root)
                 var resource = await response.AsHal();
 
                 var links = Links
-                    .RootedAt(root)
+                    .FromRequestMessage(response.RequestMessage)
                     .Index()
                     .Find()
                     .Add(Constants.Relations.Self, $"{path}?{LastLinkQuery}")
@@ -118,7 +118,8 @@ public async Task read_first_link(string path, string root)
 
                 var resource = await response.AsHal();
 
-                var links = Links.RootedAt(root)
+                var links = Links
+                    .FromRequestMessage(response.RequestMessage)
                     .Index()
                     .Find()
                     .Add(Constants.Relations.Self, $"{path}?{FirstLinkQuery}")
@@ -146,7 +147,8 @@ public async Task read_first_link_when_multiple_pages(string path, string root)
 
                 var resource = await response.AsHal();
 
-                var links = Links.RootedAt(root)
+                var links = Links
+                    .FromRequestMessage(response.RequestMessage)
                     .Index()
                     .Find()
                     .Add(Constants.Relations.Self, $"{path}?{FirstLinkQuery}")

src/SqlStreamStore.HAL/AllStream/AllStreamResource.cs

@@ -54,7 +54,7 @@ public async Task<Response> Get(
                     })
                     .AddLinks(
                         Links
-                            .RootedAt(string.Empty)
+                            .FromOperation(operation)
                             .Index()
                             .Find()
                             .AllStreamNavigation(page, operation))
@@ -74,7 +74,8 @@ public async Task<Response> Get(
                                     metadata = message.JsonMetadata
                                 })
                                 .AddLinks(
-                                    Links.RootedAt(string.Empty)
+                                    Links
+                                        .FromOperation(operation)
                                         .Add(
                                             Constants.Relations.Message,
                                             $"streams/{message.StreamId}/{message.StreamVersion}")

src/SqlStreamStore.HAL/AllStream/ReadAllStreamOperation.cs

@@ -12,6 +12,8 @@ internal class ReadAllStreamOperation : IStreamStoreOperation<ReadAllPage>
 
         public ReadAllStreamOperation(HttpRequest request)
         {
+            Path = request.Path;
+
             EmbedPayload = request.Query.TryGetValueCaseInsensitive('e', out var embedPayload)
                            && embedPayload == "1";
 
@@ -62,6 +64,7 @@ public ReadAllStreamOperation(HttpRequest request)
         public int ReadDirection { get; }
         public string Self { get; }
         public bool IsUriCanonical { get; }
+        public PathString Path { get; }
 
         public Task<ReadAllPage> Invoke(IStreamStore streamStore, CancellationToken ct)
             => ReadDirection == Constants.ReadDirection.Forwards

src/SqlStreamStore.HAL/AllStreamMessage/AllStreamMessageResource.cs

@@ -25,7 +25,8 @@ public async Task<Response> Get(
         {
             var message = await operation.Invoke(_streamStore, cancellationToken);
 
-            var links = Links.RootedAt("../")
+            var links = Links
+                .FromOperation(operation)
                 .Index()
                 .Find()
                 .Add(Constants.Relations.Message, $"stream/{message.Position}").Self()

src/SqlStreamStore.HAL/AllStreamMessage/ReadAllStreamMessageOperation.cs

@@ -10,10 +10,12 @@ internal class ReadAllStreamMessageOperation : IStreamStoreOperation<StreamMessa
     {
         public ReadAllStreamMessageOperation(HttpRequest request)
         {
+            Path = request.Path;
             Position = long.Parse(request.Path.Value.Remove(0, 2 + Constants.Streams.All.Length));
         }
 
         public long Position { get; }
+        public PathString Path { get; }
 
         public async Task<StreamMessage> Invoke(IStreamStore streamStore, CancellationToken ct)
         {

src/SqlStreamStore.HAL/IStreamStoreOperation.cs

@@ -2,9 +2,11 @@
 {
     using System.Threading;
     using System.Threading.Tasks;
+    using Microsoft.AspNetCore.Http;
 
     internal interface IStreamStoreOperation<T>
     {
+        PathString Path { get; }
         Task<T> Invoke(IStreamStore streamStore, CancellationToken cancellationToken);
     }
 }

src/SqlStreamStore.HAL/Index/IndexResource.cs

@@ -3,6 +3,7 @@ namespace SqlStreamStore.HAL.Index
     using System;
     using System.Reflection;
     using Halcyon.HAL;
+    using Microsoft.AspNetCore.Http;
     using Newtonsoft.Json;
     using Newtonsoft.Json.Linq;
 
@@ -39,7 +40,7 @@ private static string GetVersion(Type type)
         public Response Get() => new HalJsonResponse(new HALResponse(_data)
             .AddLinks(
                 Links
-                    .RootedAt(string.Empty)
+                    .FromPath(PathString.Empty)
                     .Index().Self()
                     .Find()
                     .Add(Constants.Relations.Feed, Constants.Streams.All)));