Install FDB synchronously

We were seeing CI failures where the FDB installation would not be
completed before we tried to invoke `fdbcli --version`

Fix issues caused by foundationdb.org breakage

The foundationdb.org collapse and subsequent move to GitHub created a
bit of fallout:

* Update package URLs from foundationdb.org to github.com

* Install Python package via pip as it's not published on GitHub

* Bump version to 6.3.23 as pypi has limited release selection

* Vendor the create_cluster_file.bash script (FDB elected to remove it
  from their published container builds).

Update URL for FDB packages

Deallocate future mutex in the future resource destructor

Otherwise we end up leaking mutexes https://github.com/apache/couchdb-erlfdb/issues/49

Avoid reserved keys in tests (#48)

Refactor build matrix (#43)

Rework and simplify the build through the following enhancements:

* Build against multiple Erlang/OTP versions

* Merge Ubuntu and Windows into a matrix build

* Simplify config by using default fdb.cluster

The last one is a bit obvious in hindsight. We don't need to be passing
around custom overrides for the fdb.cluster file location; all we really
need to do is just trust FDB to figure it out on each platform. To do this
we allow for setting the test_cluster_file env to `system_default` instead
of a path to a specific cluster file.

Publish coverage to coveralls.io

Enable code coverage for eunit + bindingtester

The EUnit coverage is on by default. The bindingtester can be enabled
by defining the COVER_ENABLED environment variable. It writes to the
same directory that EUnit does; namely "_build/test/cover/" if ERL_LIBS
is defined to point to the "test" profile for erlfdb (as it should be
for code coverage analysis). For example:

COVER_ENABLED=1 ERL_LIBS=_build/test/lib/erlfdb /usr/src/foundationdb/bindings/bindingtester/bindingtester.py erlang --test-name api --instruction-prefix api --num-ops 10000

We could try to be a little smarter here and align to rebar3's config
options, but I didn't bother with that for now.

Implement wrapper for get_estimated_range_size API

This is new in 6.3.

Support 6.2.x and 6.3.x in devcontainer

6.3 changed the bindingtester code to use Python3, so we need to make
sure to install the Python bindings (used by the binding tester) with
the right version of Python conditional on the minor version of FDB.

Add a matrix job to run binding tests

This job uses the same container image as the .devcontainer. It runs
each of the binding tests for every supported API version (currently
620 and 630), except for `scripted` which only works with the current
API version. It relies on a service container for the underlying FDB
server.

Fix OOB array access in get_string_array

Silly bug here, but we didn't catch because for some reason the
get_addresses_for_key function is not part of the bindings tester
specifications. I added a brutally simply unit test to cover it.

Merge pull request #37 from apache/configure-fdb-version

Configure FDB_API_VERSION dynamically, add full support for FDB 6.3.x

Merge pull request #33 from apache/erlfmt

Format code using erlfmt

Add support for ENABLE_RUN_LOOP_PROFILING

This is the new name for ENABLE_SLOW_TASK_PROFILING.

Build against latest 6.2 / 6.3 in CI

Detect FDB_API_VERSION from fdbcli --version

Remove CXXFLAGS (this is not C++)

Allow command-line override of FDB_API_VERSION

Ensure erlfmt compliance in CI

Format code using erlfmt

Add erlfmt as a project_plugin

Add a dev container configuration for VS Code (#27)

This creates a development environment with a FoundationDB server and
an erlfdb client in two containers, sharing a network through Docker
Compose.

It uses the FDB image published to Docker Hub for the FDB container, and
downloads the FDB client packages from foundationdb.org to provide the
development headers and libraries. Once the Docker Compose setup is
created, VS Code executes the `create_cluster_file.bash` script to write
down a cluster file containing the IP address in the compose network
where the FDB service can be found, and initializes the FDB server with
a new database.

The use of an external FDB container allows the erlfdb container to be
re-created as needed without losing the underlying data in the FDB
container.

Restore ignores for rebar2 artifacts

Enable CI using GitHub Actions

This patch sets up a simple GH Action configuration to build and unit
test erlfdb on Windows and Linux. We could get a lot fancier here; my
initial goal was simply to avoid regressions in x-platform support.

I'm using a handful of third-party actions to make this setup work:

- https://github.com/erlef/setup-beam
- https://github.com/ilammy/msvc-dev-cmd
- https://github.com/mxschmitt/action-tmate

ASF policy prohibits the direct use of third-party Actions because it's
not possible to code review each chamnge to them. Importing them as a
submodule pins the action to a specific commit and is the accepted
workaround at this time.

Upgrade to rebar3, add Windows support

This patch updates erlfdb to build using rebar3. It relies on rebar3's
`pc` plugin to build the NIF instead of the compiled copy of davisp's
erlang-native-compiler, which does essentially the same thing. I left
the rebar_gdb_plugin code in the repo, although I did not update that
plugin to make it compatible with rebar3 yet.

With rebar3 in place, I also made the changes necessary to support
Windows. One gotcha is that the unit tests will fail unless you set
the erlfdb test_cluster_file environment variable to point to a running
fdb.cluster file. I didn't get through all the hoops to make the
approach of spinning up an embedded fdbserver work in a x-platform way.
Apparently Windows doesn't let you supply a Python script for the
spawn_executable argument of erlang:open_port/2. I added a rebar3
profile to help here. The following command will cause the test suite
to connect to an FDB server that is managing its configuration in the
default location on Windows:

  rebar3 as win32_external_fdbserver eunit

Make dialyzer happy (#32)

* Update a couple of type specs to match reality
* Remove dead code

Minor update to metadata

Enable GH issues (#28)

Ensure application environment is loaded (#26)

erlfdb is a library application, but starting the app is still
required to make the application environment variables accessible.
Without this hack the `test_cluster_file` setting has no effect during
eunit test executions.

Update enc (port compiler) to work with Erlang 23

Make the default wait timeout infinity (continued)

This the continuation of https://github.com/apache/couchdb-erlfdb/pull/22. There,
we updated only one `after` clause and forgot the other. The reasoning is the
same as before -- make erlfdb behave consistent with other FDB clients which
do not have top level client-side timeouts for futures.

Make the default wait timeout infinity

This brings the default behavior in line with other FoundationDB client
libraries which don't use client-side timeouts when waiting for futures to
fire.

A few other reasons are:

  * Currently we may generate spurious future `ready` messages when timeouts
fire during overload scenarios. The caller would have to know to flush ready
messages if they caught a `{timeout, _}`

 * The response may succeed under 5 seconds, but it would be queued in the
   networking layer and throw a `timeout` error on the Erlang side.

 * Timeouts can be set as a transaction or db handle options. It's easier to
   apply configuration defaults there than for individual wait functions.

 * Watch futures are not bound by the 5 second transaction time limit, and
   they'd have to know about the default `wait/1,2` call timeout to know to
   extend it or set it to `infinity`.

Add ERLFDB_IS_RETRYABLE/2 guard

This is a guard which may be used to catch and handle retryable errors. It's
more ergonomic as a guard than a function, since the handler won't have to
catch and re-throw unwanted (non-retryable) exceptions.

Along with a guard, some common FDB error codes are also defined. It's not an
exhaustive list and mostly consists of retryable and a few other common errors.

Make monitor.py use /usr/bin/env python3

Previously it was set to `/usr/bin/python`, however on later versions
of Ubuntu and other OSes `/usr/bin/python` is missing. Users may install the
`python-is-python3` package but that is not ideal.

Merge pull request #19 from skunkwerks/fix/bsd-hier

look in /usr/local/bin/ before /usr/local/sbin/

look in /usr/local/bin/ before /usr/local/sbin/

according to [heir(7)](https://man.freebsd.org/cgi/hier) /sbin/ is for
binaries fundamental to single-user and multi-user environments, which
fdb is definitely not.

Fix erlfdb_database_set_option `else` case

This was detected with more a recent compiler as an uninitialized variable:

```
c_src/main.c: In function 'erlfdb_database_set_option':
c_src/main.c:818:9: error: 'option' may be used uninitialized in this function [-Werror=maybe-uninitialized]
```

Revert "look in /usr/local/bin/ before /usr/local/sbin/"

This reverts commit 9ebcc0957cdb9d3a32761b5b25cc6777e3266411.

Revert "update enc to allow building on OTP23+"

This reverts commit 0eeca574cc0f0d93d383897a869afc5844ac65e9.

Use client buggify options on the client

Previously we used plain buggify options which are meant for the server. Switch
them to the client versions.

Can check if it works with: ```
ERL_ZFLAGS="-erlfdb network_options '[client_buggify_enable, {client_buggify_section_activated_probability, 60}, {client_buggify_section_fired_probability, 60}]'" make elixir tests=test/elixir/test/basics_test.exs
```

look in /usr/local/bin/ before /usr/local/sbin/

according to [heir(7)](https://man.freebsd.org/cgi/hier) /sbin/ is for
binaries fundamental to single-user and multi-user environments, which
fdb is definitely not.

update enc to allow building on OTP23+

Also as far back as OTP21. In 2021, the Ericsson OTP team only
officially support OTP22 & OTP23, and in 2022, OTP 24 will replace
OTP22.

See  https://github.com/davisp/erlang-native-compiler/pull/2

Merge pull request #15 from apache/freebsd

Add /usr/local/{include|lib} to CFLAGS/LDFLAGS

Add /usr/local/{include|lib} to CFLAGS/LDFLAGS

Allow fold_range_wait in snapshot mode (#14)

This is just a convenience function in case the calling code happens
to supply an erlfdb_snapshot structure instead of an erlfdb_transaction.
It has no actual effect on the semantics since this is merely waiting
on the previously-created future.

Avoid sending future ready messages when flushed

There's a small race condition in `erlfdb:flush_future_message` if the
`is_ready` returns true before the future's callback is invoked to send
the ready message. This adds an API to silence the message from a future
to close this race condition.

Fixes apache/couchdb#3294

Idempotent snapshot handle setting

If a transaction handle is already a snapshot, make setting it a snapshot again
a no-op.

Merge pull request #10 from apache/report-conflicting-keys

Add support for reporting conflicting keys

Add support for reporting conflicting keys

Transactions that fail due to a conflict can be hard to debug. This
exposes a recent feature that reports keys that were in conflict if a
transaction has to be retried due to a conflict.

Do not apply default future timeouts to commit and on_error response

`commit` should timeout based on the default transaction_too_old (1007) error
or from an explicitly set transaction timeout option (1031).

`on_error` may sleep for some time which is determined by the backoff and retry
counts,it is limited and is guaranteed to return back.

Cancel fold range futures

Previously we had functions to create and wait on fold range futures, but no way
to cancel them. This commit add clauses to `cancel/1,2` to do just that.

Also, once the `?IS_FOLD_FUTURE` macro is defined, use it in a few function
heads instead of the previously used `{fold_info, _, _}` tuple.

Merge pull request #6 from apache/fix-monitor-path-detection

code:priv_dir/1 expects application name

code:priv_dir/1 expects application name

Avoid the system key range in the eunit test random key generator.

Previously the generator could sometimes return values in the system
range and tests would fail with the unexpected 2004 error.

Allow setting some default transaction options on the db handle

Since FDB version 6.1 [1] it is possible to set default transaction
options on database handles, and any transactions created from that
handle will inherit those options.

[1] https://apple.github.io/foundationdb/old-release-notes/release-notes-610.html

Add .asf.yaml file for commits and notifications

Instructions from [Apache Infra](https://cwiki.apache.org/confluence/display/INFRA/.asf.yaml+features+for+git+repositories#id-.asf.yamlfeaturesforgitrepositories-Notificationsettingsforrepositories)

Do not commit read-only transactions

This might save a round-trip to the network thread [1]. It also follows the
recommendation in the C api docs [2].

[1] https://forums.foundationdb.org/t/performance-of-read-only-transactions/1998
[2] https://apple.github.io/foundationdb/api-c.html#c.fdb_transaction_commit

However, it turns out in order for the watches to fire the read-only
transaction still has to commit, so avoid this optimization if has_watches(Tx)
is true.

Implement has_watches(Tx) transaction flag

Returns true if transaction has created any watches. If writes are disallowed,
watches are also cannot be created.

Merge pull request #1 from apache/dont-create-new-tx-object-on-retries

Do not create a new transaction object during retries

Do not create a new transaction object during retries

`on_error` function automatically resets the transaction object but
preserves retry and backoff-related information in the object. Avoid
creating a new transaction object which would lose that context in
case transactions retry more than 2 times.

Reference:
https://apple.github.io/foundationdb/api-c.html#c.fdb_transaction_on_error

Merge pull request #17 from cloudant-labs/encode-lists-like-binaries

erlfdb_tuple:encode/2 should handle lists through binary conversion

erlfdb_tuple:encode/2 should provide a clear error message when provided
with a bad term to encode

Add transaction option to disallow writes

Add `disallow_writes | allow_writes` transaction options.

If the transaction hasn't done any writes yet, it is possible to set the
`disallow_writes` option, and then every write attempt will throw a
`writes_not_allowed` error.

Bump API level to 620

This comes with a few changes:

 * `fdb_future_get_version` was renamed to `fdb_future_get_int64`
 * a new API: `fdb_transaction_get_approximate_size`
 * `size_limit` transaction option

Reference: https://apple.github.io/foundationdb/release-notes.html#bindings

Merge pull request #9 from cloudant-labs/add-get-error-string

Expose error string description function in the API

Expose error string description function in the API

Add instructions on running the fdb bindingtester

Merge pull request #6 from cloudant-labs/update-api-level-to-610

Switch API level to 610

Switch API level to 610

There were some changes that had to be accounted for:

 * Cluster is gone, so cluster futures, resources, etc were removed

 * Create database returns a database object not future, so database future
   type is removed.

 * It's possible to use json tracing format on the client, so added that
   netowrk option.

Add a debug utility function

Ensure intialization of offset

If we don't initialize offset here its possible that a key selector
could apply the provided offset to an uninitialized value passed in from
the calling function.

Adding a better README

Replace get_range_raw with fold_range_future/wait

This has been bugging me for awhile in that we're not properly handling
the return value from the range future. The `more` return value in
particular was ignored.

Rather than force people to have to repeatedly reimplement this I've
changed `get_range_raw` with a pair of functions `fold_range_future` and
`fold_range_wait`. This allows us the benefit of the async approach
while also ensuring we're not dealing with partial ranges being returned
to users.

Merge pull request #5 from cloudant-labs/improve-message-flushing

Improve message flushing

Improve message flushing when waiting for a future

Re-use the same function as cancel/2. Also, flush after getting the result to
decreases the change of the message being missed.

Add cancel/2 function, which takes an options argument

When futures are canceled, they may have a `ready` message already in the
mailbox. There is now a way to flush that message with the `[flush]` option.
That is currently the only option.

Remember to free the msg_env on future destruction

Mark futures as cancelled

This allows callers to cancel futures without having to worry about
receiving a `ready` message if the future completes before the
cancellation is applied.

Its possible that a message for this already in the callers message
queue. In which case you can call `cancel(Future, [flush])` to remove
that message.

Fix reference counting of ErlFDBFuture resources

I forgot to account for the fact that we need to keep a reference to the
ErlFDBFuture resources while they are being processed by the network
thread. This change accounts for that fact.

Make erlfdb_get_key_selector more user friendly

Previously it was not possible to combine the `lt`/`lteq`/`gt`/`gteq`
behaviors with an offset without duplicating all of the logic in
`erlfdb_get_key_selector`. This changes that so a skip can be applied
onto any of those atom based selectors.

Add get_next_tx_id API

This API provides a transaction ID that can be used in the 12 byte
version stamps to distinguish between version stamps created in a single
transaction. There's a limit of 65,535 transaction ids afterwhich this
function starts throwing badarg exceptions.

Expose get_raw_range

This allows clients to access the raw futures for range requests.
Clients of this API are then required to manager their own iteration
state and continuation logic.

Fix get_last_error/1

Make sure to use the correct `get/1` function.

Add utilities for creating test clusters

These utilities allow us to setup a test cluster for use during unit
tests. By default this will setup a cluster once per VM and also re-use
state from old test runs if it exists. Tests should ensure an empty
cluster when necessary by specifying the `empty` option when calling
`erlfdb_util:get_test_db/1`.

Flush `ready` message if already sent

Release future resources properly

This prevented all future objects from being properly garbage collected.

Add an API for getting the previous error

Expose is_read_only/1 API

Store the error code for clients

Clients of the transactional API may need to refer to which error
occurred in order to react appropriately on transaction retries.

Add tracking of read only transactions

Only unpack the tail after the provided prefix

Export unpack/2

Allow specifying a prefix for unpack and range

This pretty much removes any usefulness from `erlfdb_subspace` since
Erlang doesn't support operator overrides or other similar syntactic
sugar that makes subspaces useful in other languages.

Update directory-layer-design.md

Just small typos I observed on reviewing the notes.

Match Python catching all exceptions

Implement the DirectoryLayer

This implements a DirectoryLayer intends to behave identically to the
Python version. Soak tests have so far run as long as an hour without
finding issues. However I plan on trying to get that number to upwards
of 24 hours or more.

Fix wait_for_empty calls in concurrent testing

Use the new snapshot object for API tests

Fix test runs with concurrency