docs: DOs and DONTs

CHANGELOG.md

@@ -14,7 +14,7 @@ The `Unreleased` section name is replaced by the expected version of next releas
 
 ### Changed
 
-- Target `Equinox` v `4.0.0-rc.14.5`, `Propulsion` v `3.0.0-rc.9.11`, `FsCodec` v `3.0.0-rc.14.1` [#131](https://github.com/jet/dotnet-templates/pull/131)
+- Target `Equinox` v `4.0.0-rc.16`, `Propulsion` v `3.0.0-rc.10`, `FsCodec` v `3.0.0-rc.15` [#131](https://github.com/jet/dotnet-templates/pull/131)
 - Target `Argu` v `6.0.14` [#135](https://github.com/jet/dotnet-templates/pull/135)
 
 ### Removed 

equinox-patterns/Domain/Domain.fsproj

@@ -17,10 +17,10 @@
 
   <ItemGroup>
     <!-- Equinox.Core.Batching -->
-    <PackageReference Include="Equinox.Core" Version="4.0.0-rc.14.5" />
-    <PackageReference Include="Equinox.MemoryStore" Version="4.0.0-rc.14.5" />
-    <PackageReference Include="Equinox.CosmosStore" Version="4.0.0-rc.14.5" />
-    <PackageReference Include="FsCodec.SystemTextJson" Version="3.0.0-rc.14.1" />
+    <PackageReference Include="Equinox.Core" Version="4.1.0-rc.1" />
+    <PackageReference Include="Equinox.MemoryStore" Version="4.1.0-rc.1" />
+    <PackageReference Include="Equinox.CosmosStore" Version="4.1.0-rc.1" />
+    <PackageReference Include="FsCodec.SystemTextJson" Version="3.1.0-rc.3" />
   </ItemGroup>
 
 </Project>

equinox-patterns/Domain/ExactlyOnceIngester.fs

@@ -65,7 +65,7 @@ type Service<[<Measure>]'id, 'req, 'res, 'outcome> internal
     ///   a) back-off, re-read and retry if there's a concurrent write Optimistic Concurrency Check failure when writing the stream
     ///   b) enter a prolonged period of retries if multiple concurrent writes trigger rate limiting and 429s from CosmosDB
     ///   c) readers will less frequently encounter sustained 429s on the batch
-    let batchedIngest = Equinox.Core.Batching.Batcher(tryIngest, linger)
+    let batchedIngest = Equinox.Core.Batching.Batcher(tryIngest, Linger = linger)
 
     /// Run the requests over a chain of epochs.
     /// Returns the subset that actually got handled this time around (i.e., exclusive of items that did not trigger writes per the idempotency rules).

equinox-patterns/Domain/Store.fs

@@ -11,12 +11,12 @@ module Codec =
     let gen<'t when 't :> TypeShape.UnionContract.IUnionContract> =
         FsCodec.SystemTextJson.Codec.Create<'t>() // options = Options.Default
     let genJsonElement<'t when 't :> TypeShape.UnionContract.IUnionContract> =
-        FsCodec.SystemTextJson.CodecJsonElement.Create<'t>() // options = Options.Default
+        FsCodec.SystemTextJson.CodecJsonElement.Create<'t>() |> FsCodec.SystemTextJson.Encoder.Uncompressed // options = Options.Default
 
 module Memory =
 
     let create name codec initial fold store: Equinox.Category<_, _, _> =
-        Equinox.MemoryStore.MemoryStoreCategory(store, name, FsCodec.Compression.EncodeUncompressed codec, fold, initial)
+        Equinox.MemoryStore.MemoryStoreCategory(store, name, FsCodec.Encoder.Uncompressed codec, fold, initial)
 
 let private defaultCacheDuration = System.TimeSpan.FromMinutes 20
 let private cacheStrategy cache = Equinox.CachingStrategy.SlidingWindow (cache, defaultCacheDuration)

equinox-shipping/Domain.Tests/Domain.Tests.fsproj

@@ -20,7 +20,7 @@
         <PackageReference Include="Microsoft.NET.Test.Sdk" Version="17.2.0" />
 
         <PackageReference Include="FsCheck.Xunit" Version="3.0.0-beta2" />
-        <PackageReference Include="Propulsion.MemoryStore" Version="3.0.0-rc.9.11" />
+        <PackageReference Include="Propulsion.MemoryStore" Version="3.0.0-rc.14.10" />
         <PackageReference Include="xunit" Version="2.4.2" />
         <PackageReference Include="xunit.runner.visualstudio" Version="2.4.5" />
     </ItemGroup>

equinox-shipping/Domain.Tests/FinalizationProcessTests.fs

@@ -43,7 +43,7 @@ type Properties(testOutput) =
         test <@ res1 && set eventTypes = set expectedEvents @>
         let containerEvents =
             buffer.Queue(Container.Reactions.streamName containerId1)
-            |> Seq.chooseV (FsCodec.Compression.EncodeUncompressed Container.Events.codec).Decode 
+            |> Seq.chooseV (FsCodec.Encoder.Uncompressed Container.Events.codec).Decode 
             |> List.ofSeq
         test <@ match containerEvents with
                 | [ Container.Events.Finalized e ] -> e.shipmentIds = requestedShipmentIds

equinox-shipping/Domain/Domain.fsproj

@@ -20,11 +20,11 @@
     </ItemGroup>
 
     <ItemGroup>
-      <PackageReference Include="Equinox.CosmosStore" Version="4.0.0-rc.14.5" />
-      <PackageReference Include="Equinox.DynamoStore" Version="4.0.0-rc.14.5" />
-      <PackageReference Include="Equinox.EventStoreDb" Version="4.0.0-rc.14.5" />
-      <PackageReference Include="Equinox.MemoryStore" Version="4.0.0-rc.14.5" />
-      <PackageReference Include="FsCodec.SystemTextJson" Version="3.0.0-rc.14.1" />
+      <PackageReference Include="Equinox.CosmosStore" Version="4.1.0-rc.1" />
+      <PackageReference Include="Equinox.DynamoStore" Version="4.1.0-rc.1" />
+      <PackageReference Include="Equinox.EventStoreDb" Version="4.1.0-rc.1" />
+      <PackageReference Include="Equinox.MemoryStore" Version="4.1.0-rc.1" />
+      <PackageReference Include="FsCodec.SystemTextJson" Version="3.1.0-rc.3" />
     </ItemGroup>
 
 </Project>

equinox-shipping/Domain/Store.fs

@@ -14,12 +14,12 @@ module Codec =
     let gen<'t when 't :> TypeShape.UnionContract.IUnionContract> =
         Codec.Create<'t>(options = defaultOptions)
     let genJsonElement<'t when 't :> TypeShape.UnionContract.IUnionContract> =
-        CodecJsonElement.Create<'t>(options = defaultOptions)
+        CodecJsonElement.Create<'t>() // options = Options.Default
 
 module Memory =
 
     let create name codec initial fold store: Equinox.Category<_, _, _> =
-        Equinox.MemoryStore.MemoryStoreCategory(store, name, FsCodec.Compression.EncodeUncompressed codec, fold, initial)
+        Equinox.MemoryStore.MemoryStoreCategory(store, name, FsCodec.Encoder.Uncompressed codec, fold, initial)
 
 let private defaultCacheDuration = System.TimeSpan.FromMinutes 20
 let private cacheStrategy cache = Equinox.CachingStrategy.SlidingWindow (cache, defaultCacheDuration)
@@ -29,7 +29,7 @@ module Cosmos =
     open Equinox.CosmosStore
 
     let private createCached name codec initial fold accessStrategy (context, cache) =
-        CosmosStoreCategory(context, name, codec, fold, initial, accessStrategy, cacheStrategy cache)
+        CosmosStoreCategory(context, name, FsCodec.SystemTextJson.Encoder.Compressed codec, fold, initial, accessStrategy, cacheStrategy cache)
 
     let createSnapshotted name codec initial fold (isOrigin, toSnapshot) (context, cache) =
         let accessStrategy = AccessStrategy.Snapshot (isOrigin, toSnapshot)
@@ -40,7 +40,7 @@ module Dynamo =
     open Equinox.DynamoStore
 
     let private createCached name codec initial fold accessStrategy (context, cache) =
-        DynamoStoreCategory(context, name, FsCodec.Compression.EncodeTryCompress codec, fold, initial, accessStrategy, cacheStrategy cache)
+        DynamoStoreCategory(context, name, FsCodec.Encoder.Compressed codec, fold, initial, accessStrategy, cacheStrategy cache)
 
     let createSnapshotted name codec initial fold (isOrigin, toSnapshot) (context, cache) =
         let accessStrategy = AccessStrategy.Snapshot (isOrigin, toSnapshot)

equinox-shipping/Domain/TransactionWatchdog.fs

@@ -12,7 +12,7 @@ module Events =
         | NonTerminal of DateTimeOffset
         | Terminal
     let createCategorizationCodec isTerminalEvent =
-        let tryDecode (encoded: FsCodec.ITimelineEvent<ReadOnlyMemory<byte>>) =
+        let tryDecode (encoded: FsCodec.ITimelineEvent<FsCodec.Encoded>) =
             ValueSome (if isTerminalEvent encoded then Terminal else NonTerminal encoded.Timestamp)
         let encode _ = failwith "Not Implemented"
         let mapCausation () _ = failwith "Not Implemented"

equinox-shipping/Watchdog.Lambda.Cdk/Watchdog.Lambda.Cdk.fsproj

@@ -20,7 +20,7 @@
         <!-- jsii Roslyn analyzers (un-comment to obtain compile-time checks for missing required props-->
         <!-- <PackageReference Include="Amazon.Jsii.Analyzers" Version="*" PrivateAssets="all" />-->
 
-        <PackageReference Include="Propulsion.DynamoStore.Constructs" Version="3.0.0-rc.9.11" />
+        <PackageReference Include="Propulsion.DynamoStore.Constructs" Version="3.0.0-rc.14.10" />
     </ItemGroup>
 
 </Project>

equinox-shipping/Watchdog.Lambda/Watchdog.Lambda.fsproj

@@ -16,7 +16,7 @@
     <ItemGroup>
         <PackageReference Include="Amazon.Lambda.Core" Version="2.1.0" />
         <PackageReference Include="Amazon.Lambda.Serialization.SystemTextJson" Version="2.3.0" />
-        <PackageReference Include="Propulsion.DynamoStore.Lambda" Version="3.0.0-rc.9.11" />
+        <PackageReference Include="Propulsion.DynamoStore.Lambda" Version="3.0.0-rc.14.10" />
     </ItemGroup>
     <ItemGroup>
       <ProjectReference Include="..\Watchdog\Watchdog.fsproj" />

equinox-shipping/Watchdog/Args.fs

@@ -42,7 +42,6 @@ module Cosmos =
         | [<AltCommandLine "-s">]           Connection of string
         | [<AltCommandLine "-d">]           Database of string
         | [<AltCommandLine "-c">]           Container of string
-        | [<AltCommandLine "-o">]           Timeout of float
         | [<AltCommandLine "-r">]           Retries of int
         | [<AltCommandLine "-rt">]          RetriesWaitTime of float
         interface IArgParserTemplate with
@@ -52,18 +51,16 @@ module Cosmos =
                 | Connection _ ->           "specify a connection string for a Cosmos account. (optional if environment variable EQUINOX_COSMOS_CONNECTION specified)"
                 | Database _ ->             "specify a database name for Cosmos store. (optional if environment variable EQUINOX_COSMOS_DATABASE specified)"
                 | Container _ ->            "specify a container name for Cosmos store. (optional if environment variable EQUINOX_COSMOS_CONTAINER specified)"
-                | Timeout _ ->              "specify operation timeout in seconds (default: 5)."
                 | Retries _ ->              "specify operation retries (default: 1)."
                 | RetriesWaitTime _ ->      "specify max wait-time for retry when being throttled by Cosmos in seconds (default: 5)"
 
     type Arguments(c: Configuration, p: ParseResults<Parameters>) =
         let connection =                    p.GetResult(Connection, fun () -> c.CosmosConnection)
         let discovery =                     Equinox.CosmosStore.Discovery.ConnectionString connection
         let mode =                          p.TryGetResult ConnectionMode
-        let timeout =                       p.GetResult(Timeout, 5.) |> TimeSpan.FromSeconds
         let retries =                       p.GetResult(Retries, 1)
         let maxRetryWaitTime =              p.GetResult(RetriesWaitTime, 5.) |> TimeSpan.FromSeconds
-        let connector =                     Equinox.CosmosStore.CosmosStoreConnector(discovery, timeout, retries, maxRetryWaitTime, ?mode = mode)
+        let connector =                     Equinox.CosmosStore.CosmosStoreConnector(discovery, retries, maxRetryWaitTime, ?mode = mode)
         let database =                      p.GetResult(Database, fun () -> c.CosmosDatabase)
         let container =                     p.GetResult(Container, fun () -> c.CosmosContainer)
         member val Verbose =                p.Contains Verbose

equinox-shipping/Watchdog/Handler.fs

@@ -42,14 +42,14 @@ let handle
     | TransactionWatchdog.Finalization.MatchStatus (transId, state) ->
         match TransactionWatchdog.toStatus processingStuckCutoff state with
         | TransactionWatchdog.Complete ->
-            return Propulsion.Sinks.StreamResult.AllProcessed, Outcome.Completed
+            return Outcome.Completed, Propulsion.Sinks.Events.next events
         | TransactionWatchdog.Active ->
             // We don't want to be warming the data center for no purpose; visiting every second is not too expensive
             do! Async.Sleep 1000 // ms
-            return Propulsion.Sinks.StreamResult.NoneProcessed, Outcome.Deferred
+            return Outcome.Deferred, Propulsion.Sinks.Events.index events
         | TransactionWatchdog.Stuck ->
             let! success = driveTransaction transId
-            return Propulsion.Sinks.StreamResult.AllProcessed, Outcome.Resolved success
+            return Outcome.Resolved success, Propulsion.Sinks.Events.next events
     | other ->
         return failwithf "Span from unexpected category %A" other }
 

equinox-shipping/Watchdog/Infrastructure.fs

@@ -95,9 +95,10 @@ module EventStoreContext =
 
  module OutcomeKind =
 
-    let [<return: Struct>] (|StoreExceptions|_|) exn =
+    let [<return: Struct>] (|StoreExceptions|_|) (exn: exn) =
         match exn with
         | Equinox.DynamoStore.Exceptions.ProvisionedThroughputExceeded
         | Equinox.CosmosStore.Exceptions.RateLimited -> Propulsion.Streams.OutcomeKind.RateLimited |> ValueSome
-        | Equinox.CosmosStore.Exceptions.RequestTimeout -> Propulsion.Streams.OutcomeKind.Timeout |> ValueSome
+        | Equinox.CosmosStore.Exceptions.RequestTimeout -> Propulsion.Streams.OutcomeKind.Tagged "cosmosTimeout" |> ValueSome
+        | :? System.Threading.Tasks.TaskCanceledException -> Propulsion.Streams.OutcomeKind.Tagged "taskCancelled" |> ValueSome
         | _ -> ValueNone

equinox-shipping/Watchdog/SourceArgs.fs

@@ -17,7 +17,6 @@ module Cosmos =
         | [<AltCommandLine "-s">]           Connection of string
         | [<AltCommandLine "-d">]           Database of string
         | [<AltCommandLine "-c">]           Container of string
-        | [<AltCommandLine "-o">]           Timeout of float
         | [<AltCommandLine "-r">]           Retries of int
         | [<AltCommandLine "-rt">]          RetriesWaitTime of float
 
@@ -32,7 +31,6 @@ module Cosmos =
                 | Connection _ ->           "specify a connection string for a Cosmos account. (optional if environment variable EQUINOX_COSMOS_CONNECTION specified)"
                 | Database _ ->             "specify a database name for store. (optional if environment variable EQUINOX_COSMOS_DATABASE specified)"
                 | Container _ ->            "specify a container name for store. (optional if environment variable EQUINOX_COSMOS_CONTAINER specified)"
-                | Timeout _ ->              "specify operation timeout in seconds. Default: 5."
                 | Retries _ ->              "specify operation retries. Default: 9."
                 | RetriesWaitTime _ ->      "specify max wait-time for retry when being throttled by Cosmos in seconds. Default: 30."
 
@@ -44,10 +42,9 @@ module Cosmos =
     type Arguments(c: Args.Configuration, p: ParseResults<Parameters>) =
         let discovery =                     p.GetResult(Connection, fun () -> c.CosmosConnection) |> Equinox.CosmosStore.Discovery.ConnectionString
         let mode =                          p.TryGetResult ConnectionMode
-        let timeout =                       p.GetResult(Timeout, 5.) |> TimeSpan.FromSeconds
         let retries =                       p.GetResult(Retries, 9)
         let maxRetryWaitTime =              p.GetResult(RetriesWaitTime, 30.) |> TimeSpan.FromSeconds
-        let connector =                     Equinox.CosmosStore.CosmosStoreConnector(discovery, timeout, retries, maxRetryWaitTime, ?mode = mode)
+        let connector =                     Equinox.CosmosStore.CosmosStoreConnector(discovery, retries, maxRetryWaitTime, ?mode = mode)
         let database =                      p.GetResult(Database, fun () -> c.CosmosDatabase)
         let containerId =                   p.GetResult(Container, fun () -> c.CosmosContainer)
         let leaseContainerId =              p.GetResult(LeaseContainer, containerId + "-aux")

equinox-shipping/Watchdog/Watchdog.fsproj

@@ -18,10 +18,10 @@
 
     <ItemGroup>
         <PackageReference Include="Argu" Version="6.1.4" />
-        <PackageReference Include="Propulsion.CosmosStore" Version="3.0.0-rc.9.11" />
-        <PackageReference Include="Propulsion.DynamoStore" Version="3.0.0-rc.9.11" />
-        <PackageReference Include="Propulsion.EventStoreDb" Version="3.0.0-rc.9.11" />
-        <PackageReference Include="Propulsion.MemoryStore" Version="3.0.0-rc.9.11" />
+        <PackageReference Include="Propulsion.CosmosStore" Version="3.0.0-rc.14.10" />
+        <PackageReference Include="Propulsion.DynamoStore" Version="3.0.0-rc.14.10" />
+        <PackageReference Include="Propulsion.EventStoreDb" Version="3.0.0-rc.14.10" />
+        <PackageReference Include="Propulsion.MemoryStore" Version="3.0.0-rc.14.10" />
         <PackageReference Include="Serilog.Sinks.Console" Version="4.0.1" />
     </ItemGroup>
 

equinox-testbed/Storage.fs

@@ -28,7 +28,6 @@ module Cosmos =
     type [<NoEquality; NoComparison>] Parameters =
         | [<AltCommandLine "-V">]       Verbose
         | [<AltCommandLine "-m">]       ConnectionMode of Microsoft.Azure.Cosmos.ConnectionMode
-        | [<AltCommandLine "-o">]       Timeout of float
         | [<AltCommandLine "-r">]       Retries of int
         | [<AltCommandLine "-rt">]      RetriesWaitTime of float
         | [<AltCommandLine "-s">]       Connection of string
@@ -37,7 +36,6 @@ module Cosmos =
         interface IArgParserTemplate with
             member p.Usage = p |> function
                 | Verbose ->       "Include low level Store logging."
-                | Timeout _ ->          "specify operation timeout in seconds. Default: 5."
                 | Retries _ ->          "specify operation retries. Default: 1."
                 | RetriesWaitTime _ ->  "specify max wait-time for retry when being throttled by Cosmos in seconds. Default: 5."
                 | ConnectionMode _ ->   "override the connection mode. Default: Direct."
@@ -47,10 +45,9 @@ module Cosmos =
     type Arguments(c: Configuration, p: ParseResults<Parameters>) =
         let discovery =                     p.GetResult(Connection, fun () -> c.CosmosConnection) |> Equinox.CosmosStore.Discovery.ConnectionString
         let mode =                          p.TryGetResult ConnectionMode
-        let timeout =                       p.GetResult(Timeout, 5.) |> TimeSpan.FromSeconds
         let retries =                       p.GetResult(Retries, 1)
         let maxRetryWaitTime =              p.GetResult(RetriesWaitTime, 5.) |> TimeSpan.FromSeconds
-        let connector =                     Equinox.CosmosStore.CosmosStoreConnector(discovery, timeout, retries, maxRetryWaitTime, ?mode = mode)
+        let connector =                     Equinox.CosmosStore.CosmosStoreConnector(discovery, retries, maxRetryWaitTime, ?mode = mode)
         let database =                      p.GetResult(Database, fun () -> c.CosmosDatabase)
         let container =                     p.GetResult(Container, fun () -> c.CosmosContainer)
         member _.Connect(tipMaxEvents, queryMaxItems) = connector.ConnectContext("Main", database, container, tipMaxEvents, queryMaxItems)

equinox-testbed/Store.fs

@@ -11,7 +11,7 @@ module Codec =
     let gen<'t when 't :> TypeShape.UnionContract.IUnionContract> =
         FsCodec.SystemTextJson.Codec.Create<'t>() // options = Options.Default
     let genJsonElement<'t when 't :> TypeShape.UnionContract.IUnionContract> =
-        FsCodec.SystemTextJson.CodecJsonElement.Create<'t>() // options = Options.Default
+        FsCodec.SystemTextJson.CodecJsonElement.Create<'t>() |> FsCodec.SystemTextJson.Encoder.Uncompressed // options = Options.Default
 
 module Memory =
 

equinox-testbed/Testbed.fsproj

@@ -17,11 +17,11 @@
 
   <ItemGroup>
     <PackageReference Include="Argu" Version="6.1.4" />
-    <PackageReference Include="Equinox.CosmosStore" Version="4.0.0-rc.14.5" />
-    <PackageReference Include="Equinox.EventStoreDb" Version="4.0.0-rc.14.5" />
-    <PackageReference Include="Equinox.MemoryStore" Version="4.0.0-rc.14.5" />
-    <PackageReference Include="Equinox.Tools.TestHarness" Version="4.0.0-rc.14.5" />
-    <PackageReference Include="FsCodec.SystemTextJson" Version="3.0.0-rc.14.1" />
+    <PackageReference Include="Equinox.CosmosStore" Version="4.1.0-rc.1" />
+    <PackageReference Include="Equinox.EventStoreDb" Version="4.1.0-rc.1" />
+    <PackageReference Include="Equinox.MemoryStore" Version="4.1.0-rc.1" />
+    <PackageReference Include="Equinox.Tools.TestHarness" Version="4.1.0-rc.1" />
+    <PackageReference Include="FsCodec.SystemTextJson" Version="3.1.0-rc.3" />
     <PackageReference Include="Microsoft.Extensions.DependencyInjection" Version="5.0.2" />
     <PackageReference Include="Serilog.Sinks.Console" Version="4.0.1" />
     <PackageReference Include="Serilog.Sinks.Seq" Version="4.0.0" />