Khepri 0.17.0

At this point, Khepri should be considered Beta and not production ready. The API will likely evolve and future releases will likely introduce breaking changes. The goal of this release is to make it easy for anyone to try it and possibly give feedback.

What's new in Khepri 0.17.0

Return tree nodes deteled by keep-while conditions in put and delete return values

All put and delete operations now return all nodes that were deleted by the operation. This includes nodes deleted by keep-while conditions as well as child tree nodes in the case of delete operations. See #305 and #309.

The deletion reason was added in the return tree node properties to allow the caller to distinguish nodes explicitly deleted from the nodes that were deleted as a consequence of a put or delete.

To permit that, the return values of advanced put and delete operations were made uniform with other operations, always returning a map of tree node properties (#303, #310). Here is an example of the change to make to your code:

• Up to Khepri 0.16.x:

  {ok, #{payload_version := _}} = khepri_adv:put(StoreId, Path, Value)

• Starting from Khepri 0.17.0:

  {ok, #{Path := #{payload_version := _}}} = khepri_adv:put(StoreId, Path, Value)

Backward-compatible transaction functions

The breaking change above impacted the khepri_tx_adv API as well and you may need to rework transactions to take into account the possible old and new return values. Indeed, transactions submitted from a Khepri member are executed on all cluster members, regardless of the version of Khepri running there. An old node might submit a transaction executed on a new node, and a new node might submit a transaction executed on an old node.

You can use the new khepri_tx:does_api_comply_with/1 to determine what to expect. Here is an example:

khepri:transaction(
  StoreId,
  fun () ->
          %% We query Khepri to determine how the API will behave.
          UsesUniformWriteRet = try
                                    khepri_tx:does_api_comply_with(uniform_write_ret)
                                catch
                                    error:undef ->
                                        false
                                end,

          %% We use the result to match the return value appropriately. This
          %% transaction function willl work equally on Khepri 0.17.0 and older
          %% versions.
          case khepri_tx_adv:delete(Path) of
              {ok, #{Path := #{data := _}}} when UsesUniformWriteRet ->
	          %% The API used the new return value format.
		  ...;
              {ok, #{data := _}} when not UsesUniformWriteRet ->
	          %% The API used the old return value format.
		  ...;
              {ok, _} ->
                  ok
          end
  end, rw).

See #326.

Optimize the lookup of matching keep_while conditions

Khepri uses a new khepri_prefix_tree internal structure instead of the previous map to manage the reverse index. This allows to quickly eliminate non-matching entries.

See #298.

Unify khepri_cluster:members/2 and khepri_cluster:nodes/2 with other query APIs

khepri_cluster:members/2 and khepri_cluster:nodes/2 now take a query options map (see the documentation of the khepri:query_options() type) instead of a timeout value only.

This allows to select between a leader query and a local query with the same favor option as any store query function. Therefore, favor => consistency will use a leader query while favor => low_latency will use a local query.

Here is an example of the change to make to your code:

• Up to Khepri 0.16.x:

  khepri_cluster:members(StoreId, Timeout),
  khepri_cluster:locally_known_nodes(StoreId)

• Starting from Khepri 0.17.0:

  khepri_cluster:members(StoreId, #{timeout => Timeout}),
  khepri_cluster:nodes(StoreId, #{favor => low_latency})

See #300.

Other changes

• Allow calls to khepri_path in transactions (#312).
• Make the internal khepri_tree:tree_v*() and khepri_tree:keep_while_conds_revidx_v*() types opaque types (#299).
• Handle expired dedups on tick to remove some load on commands (#297).
• Ignore unknown props to return to take machine breaking changes into account (#308).
• Fix bang function return value spec (#311).
• Fix documentation (#316, #321).
• Fix how we determine the need for a fence preliminary query (#317).
• Fix how we check for the dedup mechanism support (#320).
• Filter query/command options that are passed to transactions (#322, #327).
• Fix keep_while corner cases (#324).
• Horus was bumped from 0.3.0 to 0.3.1 (#307).
• Ra was bumped from 2.14.0 to 2.16.6 (#306, #314, #318, #323, #325).

Download

Khepri is available from Hex.pm: https://hex.pm/packages/khepri/0.17.0

Upgrade

Using Rebar:

1. Update your rebar.config:

   %% In rebar.config
   {deps, [{khepri, "0.17.0"}]}.

2. Run rebar3 upgrade khepri.

Using Erlang.mk:

1. Update your Makefile:

   %% In your Makefile
   dep_khepri = hex 0.17.0

2. Remove the deps/khepri directory. The new version will be fetched the next time you build your project.

Documentation

The documentation for Khepri is available on Hex.pm.