document the :deadline option for append_batch/5

With the change in EventStoreDB 21.10.5, you can pass the deadline
for BatchAppend as a duration instead of a timestamp which is much
more sane. This change allows passing the new duration type as

    {:duration, seconds, nanos}

and adds the missing documentation for the key.

Author: the-mikedavis

CHANGELOG.md

@@ -11,6 +11,15 @@ behind new EventStoreDB versions. You should not downgrade your Spear version
 in order to avoid these features: Spear aims to keep a stable interface usable
 across all EventStoreDB versions v20+.
 
+## 1.1.0 - 2022-07-08
+
+### Added
+
+- A duration may now be specified for the `:deadline` option to
+  `Spear.append_batch/5`
+    - Passing a duration (instead of a timestamp) requires EventStoreDB
+      version 21.10.5 or higher
+
 ## 1.0.2 - 2022-06-02
 
 ### Fixed

lib/spear.ex

@@ -483,6 +483,11 @@ defmodule Spear do
     use as credentials for the request. This option overrides any credentials
     set in the connection configuration, if present. See the
     [Security guide](guides/security.md) for more details.
+  * `:deadline` - (default: `nil`) the deadline for the batch to be appended.
+    This is like `:timeout` but is interpreted on the EventStoreDB server.
+    This may be a `DateTime` or a tuple of `{seconds, nanos}` since 1970
+    (smeared) but may be a tuple `{:duration, seconds, nanos}` when using
+    EventStoreDB version 21.10.5 or higher.
   * `:timeout` - (default: `5_000`) the timeout for the initial call to
     open the batch request.
 

lib/spear/records/google.ex

@@ -9,6 +9,18 @@ defmodule Spear.Records.Google do
     end
   end
 
+  # message Timestamp {
+  #   // Represents seconds of UTC time since Unix epoch
+  #   // 1970-01-01T00:00:00Z. Must be from 0001-01-01T00:00:00Z to
+  #   // 9999-12-31T23:59:59Z inclusive.
+  #   int64 seconds = 1;
+  #
+  #   // Non-negative fractions of a second at nanosecond resolution. Negative
+  #   // second values with fractions must still have non-negative nanos values
+  #   // that count forward in time. Must be from 0 to 999,999,999
+  #   // inclusive.
+  #   int32 nanos = 2;
+  # }
   if Version.match?(System.version(), ">= 1.11.0") do
     def timestamp(%DateTime{} = datetime) do
       # google timestamp is number of seconds from the first second of 1970 (smeared)
@@ -21,4 +33,22 @@ defmodule Spear.Records.Google do
   def timestamp({seconds, nanos}) do
     {:"google.protobuf.Timestamp", seconds, nanos}
   end
+
+  # message Duration {
+  #   // Signed seconds of the span of time. Must be from -315,576,000,000
+  #   // to +315,576,000,000 inclusive. Note: these bounds are computed from:
+  #   // 60 sec/min * 60 min/hr * 24 hr/day * 365.25 days/year * 10000 years
+  #   int64 seconds = 1;
+  #
+  #   // Signed fractions of a second at nanosecond resolution of the span
+  #   // of time. Durations less than one second are represented with a 0
+  #   // `seconds` field and a positive or negative `nanos` field. For durations
+  #   // of one second or more, a non-zero value for the `nanos` field must be
+  #   // of the same sign as the `seconds` field. Must be from -999,999,999
+  #   // to +999,999,999 inclusive.
+  #   int32 nanos = 2;
+  # }
+  def duration(seconds, nanos) do
+    {:"google.protobuf.Duration", seconds, nanos}
+  end
 end

lib/spear/writing.ex

@@ -132,7 +132,10 @@ defmodule Spear.Writing do
 
   defp map_deadline(nil), do: :undefined
   # coveralls-ignore-start
-  defp map_deadline(deadline), do: {:deadline_21_10_0, Google.timestamp(deadline)}
+  defp map_deadline({:duration, seconds, nanos}),
+    do: {:deadline, Google.duration(seconds, nanos)}
+
+  defp map_deadline(timestamp), do: {:deadline_21_10_0, Google.timestamp(timestamp)}
   # coveralls-ignore-stop
 
   defp map_expected_position(revision) when is_integer(revision) and revision >= 0,