Add :queue_before_connecting option

lib/xandra/cluster.ex

@@ -283,25 +283,66 @@ defmodule Xandra.Cluster do
       which has not necessarily established any connections yet. If this option is
       an integer or `:infinity` (that is, a term of type `t:timeout/0`), then this function
       only returns when at least one node connection is established. If the timeout expires,
-      this function returns `{:error, :sync_connect_timeout}`. Available since v0.16.0.
+      this function returns `{:error, :sync_connect_timeout}`. *Available since v0.16.0*.
+
+      This is only useful in rare cases when you want to make sure that the has connected
+      at least once before returning from `start_link/1`. This is fragile though, because
+      the cluster could connect once and then drop connections right away, so this doesn't
+      mean that the cluster is connected, but rather that it *connected at least once*.
+      This is useful, for example, in test suites where you're not worried about
+      resiliency but rather race conditions. In most cases, the `:queue_before_connecting`
+      option is what you want.
       """
     ],
+    queue_before_connecting: [
+      type: :keyword_list,
+      doc: """
+      Controls how to handle requests that go through the cluster *before* the cluster
+      is able to establish a connection to **any node**. This is useful because if you
+      try to use the Xandra cluster right away after starting it, you'll likely get errors
+      since the cluster needs to establish at least a connection to at least one node first.
+      The strategy that `Xandra.Cluster` uses is to queue requests until a connection
+      is established, and at that point flush those requests. If you don't want this behaviour,
+      you can set `:buffer_size` to `0`. *Available since v0.18.0*. This option supports these
+      keys:
+      """,
+      keys: [
+        buffer_size: [
+          type: :non_neg_integer,
+          default: 100,
+          doc: """
+          The number of requests to queue in the cluster and flush as soon as a connection
+          is established.
+          """
+        ],
+        timeout: [
+          type: :timeout,
+          default: 5_000,
+          doc: """
+          How long to hold on to requests for. When this timeout expires, all requests
+          are dropped and an error is returned to the caller.
+          """
+        ]
+      ],
+      default: []
+    ],
     debug: [
       type: :any,
       doc: """
-      Same as the `:debug` option in `GenServer.start_link/3`. Available since v0.18.0.
+      Same as the `:debug` option in `GenServer.start_link/3`. *Available since v0.18.0*.
       """
     ],
     spawn_opt: [
       type: :any,
       doc: """
-      Same as the `:spawn_opt` option in `GenServer.start_link/3`. Available since v0.18.0.
+      Same as the `:spawn_opt` option in `GenServer.start_link/3`. *Available since v0.18.0*.
       """
     ],
     hibernate_after: [
       type: :any,
       doc: """
-      Same as the `:hibernate_after` option in `GenServer.start_link/3`. Available since v0.18.0.
+      Same as the `:hibernate_after` option in `GenServer.start_link/3`.
+      *Available since v0.18.0*.
       """
     ],