View Source Changelog
All notable changes to this project will be documented in this file.
The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.
Note: certain Spear versions add support for new EventStoreDB features gated 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-4-0-2024-02-02
1.4.0 - 2024-02-02
added
Added
Spear.stream!/3
now saves one network request when the server returns fewer events than the requested chunk size.- Subscriptions now send
{:caught_up, subscription_ref}
and{:fell_behind, subscription_ref}
messages on EventStoreDB versions later than 23.10.
fixed
Fixed
- A single HTTP/2 DATA frame might contain multiple messages from the EventStoreDB. Previously only the first message was handled at a time and the remaining data was buffered. Now all messages in a DATA frame are sent eagerly.
1-3-2-2023-06-12
1.3.2 - 2023-06-12
fixed-1
Fixed
- Fixed a crash on start-up when Application environment values were not
set for a
Spear.Client
module usinguse Spear.Client
. - Improved documentation for event metadata.
1-3-1-2023-04-04
1.3.1 - 2023-04-04
fixed-2
Fixed
- HTTP/2 window size is now properly checked in
Spear.Connection
before attempting to send ack, nack, and batch-append messages.- Without this fix, some ack, nack and batch-append messages could be silently dropped on busy connections.
1-3-0-2022-12-09
1.3.0 - 2022-12-09
added-1
Added
- Added documentation for setting up connection pools.
- Added
:on_connect
and:on_disconnect
hook options forSpear.Connection
which can be used for pooling.
1-2-1-2022-11-14
1.2.1 - 2022-11-14
fixed-3
Fixed
- Fixed the return values for
Spear.subscribe/4
when the subscription request fails.
For example, if a connection is made with an invalid password, Spear.subscribe/4
would previously return {:ok, %Spear.Connection.Response{}}
(an internal
struct). Now Spear.subscribe/4
returns {:error, %Spear.Grpc.Response{}}
.
1-2-0-2022-11-02
1.2.0 - 2022-11-02
added-2
Added
- Added support for Persistent Subscription RPCs introduced in server version 22.6.0:
1-1-0-2022-07-08
1.1.0 - 2022-07-08
added-3
Added
- A duration may now be specified for the
:deadline
option toSpear.append_batch/5
- Passing a duration (instead of a timestamp) requires EventStoreDB version 21.10.5 or higher
1-0-2-2022-06-02
1.0.2 - 2022-06-02
fixed-4
Fixed
0
may now be passed in the:expect
option when appending or batch appending
1-0-1-2022-05-26
1.0.1 - 2022-05-26
fixed-5
Fixed
- Fixed
Spear.stream!/3
when providing a:from
event number that does not existSpear.stream!/3
gives the empty list in this case
1-0-0-2022-05-11
1.0.0 - 2022-05-11
This release represent stability in the API. There are no functional changes between this release and v0.11.0.
0-11-0-2021-11-04
0.11.0 - 2021-11-04
added-4
Added
- Added the
:filter
option toSpear.read_stream/3
andSpear.stream!/3
- This allows one to perform a non-subscription read of the
$all
stream and use a server-side filter
- This allows one to perform a non-subscription read of the
- Added
Spear.get_supported_rpcs/2
andSpear.Client.get_supported_rpcs/1
for getting the available RPC methods implemented in the connected EventStoreDB server - Added
Spear.get_server_version/2
andc:Spear.Client.get_server_version/2
for getting the version string of the connected EventStoreDB Server
These features require the new EventStoreDB version v21.10.0 released on 2021-11-03.
changed
Changed
- According to the v21.10.0 server release notes's breaking changes section, deleting a stream that does not currently exist will now throw an error
0-10-0-2021-08-30
0.10.0 - 2021-08-30
added-5
Added
- Implemented the creation, updating, reading, and deletion of persistent
subscriptions to the
:all
stream- this feature requires EventStoreDB v21.6.0 or later
- Implemented
Spear.append_batch/5
for high-throughput asynchronous appends- this feature requires EventStoreDB v21.6.0 or later
Spear.append_batch_stream/2
has also been added for convenience
- Added
Spear.subscribe_to_stats/3
andSpear.Client.subscribe_to_stats/2
- this opens a subscription for EventStoreDB monitoring
- this feature requires EventStoreDB v21.6.0 or later
- Added a dependency on the
:event_store_db_gpb_protobfs
package- this package is just a convenience for developing spear: we can build gpb definitions for the EventStoreDB protobufs on-the-fly via the rebar3 gpb plugin, so we never need to commit the erl/hrl files for the generated gpb modules.
- this also allows other (non-Elixir even) libraries to take advantage of versioned, pre-generated gpb definitions for the EventStoreDB grpc interface
changed-1
Changed
- Non-event read responses are now discarded when reading from a stream
- this will allow the compatibility of spear v0.10.0 with the next release of EventStoreDB
- this should not change behavior with any existing EventStoreDB versions
fixed-6
Fixed
- Fixed the
Spear.set_global_acl/4
function to correctly append ACL data as an event to the$streams
metadata stream, instead of to the$streams
stream directly.
0-9-1-2021-06-01
0.9.1 - 2021-06-01
added-6
Added
- Added
Spear.park_stream/2
to the utilities API
fixed-7
Fixed
- Removed compilation of mint version in user-agent function
- This could cause a compilation error when using spear as a transitive dependency
0-9-0-2021-04-29
0.9.0 - 2021-04-29
added-7
Added
- Added a
:link
field to theSpear.Event.t/0
struct- this is used to provide accurate stream revisions and IDs in projected
streams as with
Spear.subscribe/4
or inSpear.ack/3
orSpear.nack/4
- this is used to provide accurate stream revisions and IDs in projected
streams as with
- Added
Spear.Event.id/1
andSpear.Event.revision/1
which take aSpear.Event.t/0
and give the ID and revision, respectively- these new functions respect the new
:link
field and return link information instead of event information if the link is present
- these new functions respect the new
removed
Removed
- Removed link metadata from the
Spear.Event.metadata
map's possible:link
field.- use the new top-level
:link
field asSpear.Event.link.metadata
- use the new top-level
Note that this may be a breaking change for any consumers depending on the
optional :link
field in the metadata packet. Consumers should update by
instead matching on a Spear.Event.t/0
struct in the :link
field of any
event, or by using the new Spear.Event.id/1
or Spear.Event.revision/1
functions.
0-8-1-2021-04-27
0.8.1 - 2021-04-27
added-8
Added
- Added the link's stream to the
Spear.Event.metadata.link
field
fixed-8
Fixed
- Fixed some stray references to structs which should be typed as records
- Fixed
Spear.Event.to_checkpoint/1
to carry over the:subscription
key from aSpear.Event.t/0
's metadata - Fixed a bug in
Spear.Connection.Configuration
which would incorrectly choose the:http
scheme when the:tls?
option was set totrue
0-8-0-2021-04-26
0.8.0 - 2021-04-26
added-9
Added
- Added the
:read_only?
configuration flag forSpear.Connection.Configuration
- this allows one to limit what the
Spear.Connection
will perform to read-only operations such as reading streams
- this allows one to limit what the
- Added link metadata to the
Spear.Event.metadata
packet in a new:link
field
fixed-9
Fixed
- Fixed the
:from
option in read requests (Spear.read_stream/3
,Spear.stream!/3
andSpear.subscribe/4
) to respect the new link information in metadata
0-7-0-2021-04-24
0.7.0 - 2021-04-24
added-10
Added
- Added the subscription reference returned by
Spear.subscribe/4
andSpear.connect_to_persistent_subscription/5
to- the metadata map of
Spear.Event.t/0
in the pathSpear.Event.metadata.subscription
Spear.Filter.Checkpoint.t/0
in a new field:subscription
- the
:eos
tuples in the new shape of{:eos, reference(), :closed | :dropped}
- the metadata map of
Note that this is a breaking change for any consumers matching explicitly
on :eos
tuples. Consumers relying on the prior data shape should update
like so
- def handle_info({:eos, reason}, state) do
+ def handle_info({:eos, _subscription, reason}, state) do
0-6-1-2021-04-23
0.6.1 - 2021-04-23
fixed-10
Fixed
Spear.stream!/3
now reads:from
revisions as inclusive- e.g. passing some
event
in the stream to:from
will ensure that the first element in the enumerable is^event
- the same principal applies when passing event revisions
- see #26
- if this behavior is undesirable, a Spear user may
Stream.drop/2
the initial element in the enumerable
- e.g. passing some
Spear.connect_to_persistent_subscription/5
now returns an error tuple when attempting to connect to a persistent subscription stream and group that has not yet been created.- the reason is a
Spear.Grpc.Response
struct with a status of:not_found
- the reason is a
added-11
Added
- Subscriptions may now emit
{:eos, :dropped}
in cases where the EventStoreDB explicitly terminates the subscription- this can happen if a persistent subscription is deleted while it has subscribers actively connected
- each subscriber will receive
{:eos, :dropped}
in its mailbox
0-6-0-2021-04-21
0.6.0 - 2021-04-21
added-12
Added
- Added the CRUD portions of persistent subscriptions API
- Added subscription functionality for persistent subscriptions
Spear.connect_to_persistent_subscription/5
Spear.ack/3
Spear.nack/4
- associated callbacks in
Spear.Client
changed-2
Changed
- Moved
Spear.cancel_subscription/3
under the utils API instead of streams- This function may also be used to cancel persistent subscriptions
0-5-0-2021-04-19
0.5.0 - 2021-04-19
added-13
Added
- Added the gossip API
- this API is very small: just one function
Spear.cluster_info/2
- also added
Spear.Client.cluster_info/1
- under the hood, this also added the ability to decode structured
UUIDs received from the EventStoreDB, as are received in the
Spear.ClusterMember.instance_id
field. SeeSpear.Uuid
for the interesting implementation. - added the record interface
Spear.Records.Gossip
- this API is very small: just one function
fixed-11
Fixed
- Properly grouped free-floating modules under the proper structures and types or record interface groupings in the documentation
0-4-0-2021-04-19
0.4.0 - 2021-04-19
fixed-12
Fixed
- Updated security guide to use new configuration style
added-14
Added
- Added the operations API
0-3-0-2021-04-18
0.3.0 - 2021-04-18
added-15
Added
- Added record interface modules for all remaining APIs
- Added functions for interacting with the Users API
0-2-1-2021-04-17
0.2.1 - 2021-04-17
added-16
Added
- Wrapped new ACL-related functions in
Spear.Client
0-2-0-2021-04-17
0.2.0 - 2021-04-17
changed-3
Changed
- Refactored connection configuration to go through validation
:opts
option has been renamed to:mint_opts
- credentials are passed through the
:connection_string
option or as:username
and:password
options
added-17
Added
- Implemented and documented keep-alive
- This can be configured through the
keepAliveInterval
andkeepAliveTimeout
query params in:connection_string
or by the new:keep_alive_interval
and:keep_alive_timeout
configuration options
- This can be configured through the
0-1-4-2021-04-16
0.1.4 - 2021-04-16
added-18
Added
{:eos, :closed}
is now emitted when a subscription is broken due to the connection between closed betweenSpear.Connection
and EventStoreDBSpear.Connection
now monitors subscription processes and cancels EventStoreDB subscriptions upon subscriber process exit
0-1-3-2021-04-15
0.1.3 - 2021-04-15
added-19
Added
- Added documentation and functionality for using TLS certificates
- see
Spear.Connection
and the security guide
- see
- Added documentation and functionality for setting the global stream ACL
- see
Spear.set_global_acl/4
and theSpear.Acl
module
- see
- Added functionality for getting and setting stream-level metadata.
0-1-2-2021-04-14
0.1.2 - 2021-04-14
added-20
Added
- Added dependency on
connection
- Added ping functionality for
Spear.Connection
s - Added the ability to disconnect a connection by
GenServer.call/3
ing it with:close
as the message - Added the ability to explicitly reconnect a connection by
GenServer.cast/2
ing it a message of:connect
changed-4
Changed
- Changed the internals of
Spear.Connection
to take advantage of the newConnection
dependency- A failure to connect on GenServer init for a connection will no longer take down the supervision tree
- Failures to connect will result in back-off retries in 500ms segments
- The life-cycle of the HTTP2 connection spawned by a
Spear.Connection
is now divorced from the life-cycle of theSpear.Connection
process
0-1-1-2021-04-14
0.1.1 - 2021-04-14
removed-1
Removed
- Removed dependency on
elixir-protobuf/protobuf
- see #4
- also removed all generated files from protobuf
added-21
Added
- Added dependency on
:gpb
- and associated generated erlang files
- Added
Spear.Records.*
interface for interacting with gpb-generated records
0-1-0-2021-04-12
0.1.0 - 2021-04-12
added-22
Added
- Initial implementation of a client for the streams API
- all notable functions are labeled with the
since: "0.1.0"
doc attribute
- all notable functions are labeled with the