Deliver an app's saved sends over HTTP, in order and in batches (083)

pure-serve --send OUTPUT=http://host:port/path wires an output: after
every save the owner queues the new sends as JSON (fields and groups)
and a thread per output posts them in order with X-Pure-Source,
X-Pure-Sequence and Idempotency-Key. A 2xx, or a Pure receiver's
refusal, delivers; the owner then trims. 408, 429, 5xx and no answer
are sent again after a pause growing to 10 s, other answers every 10 s:
nothing is dropped. A Pure receiver applies a delivered message with
pure_app_deliver (now taking placed fields) and advertises
X-Pure-Batch: 256; the sender then posts up to that many numbers in a
row as one JSON array (X-Pure-Count), applied in order in one burst
with one save.

Delivery kept up with orders once batched (391 deliveries/s one at a
time; a backlog of 20,000 went at 60k/s). With four clients ordering,
killing the receiver and then the sender (-9) left the receiver's count
and total equal to what the sender saved, five times and under ASan.

1 files changed, 36 insertions, 0 deletions

diff --git a/prototypes/connections/deliver.h b/prototypes/connections/deliver.h
new file mode 100644
index 0000000..f720296
--- /dev/null
+++ b/prototypes/connections/deliver.h
@@ -0,0 +1,36 @@
+#ifndef PURE_DELIVER_H
+#define PURE_DELIVER_H
+#include "module.h"
+
+/* Delivering an app's saved sends over HTTP (docs/research/083-delivery-over-http.md).
+ * A wire takes one output's sends in order: each goes as a JSON object of
+ * its fields (groups as objects inside) by POST to a URL, with the headers
+ * X-Pure-Source (the sender's name for the output), X-Pure-Sequence and
+ * Idempotency-Key, one at a time, again and again until it is delivered:
+ * a 2xx answer, or a Pure receiver's refusal (a 4xx with X-Pure-Error
+ * naming a fault: it heard the message and refused it). 408, 429, 5xx and
+ * no answer are tried again after a pause (0.1 s doubling to 10 s); another
+ * 4xx is logged and tried again every 10 s. Nothing is ever dropped: what is
+ * not delivered stays in the app's outbox, and a receiver applies a number
+ * once, so a send delivered twice (its answer lost) is harmless. */
+typedef struct PureWire PureWire;
+
+/* A wire for the output named output of m to url (http://host[:port]/path),
+ * as source; NULL with why in error when it cannot be. */
+PureWire *pure_wire_open(const PureModule *m, const char *output, const char *url, const char *source,
+                         char *error, size_t size);
+uint32_t pure_wire_output(const PureWire *);
+/* The owner's side: queue a saved send numbered after the last queued one
+ * (it is encoded now); false when it cannot be (a bytes field that is not
+ * UTF-8 has no JSON form), and the wire then stops at it. */
+bool pure_wire_queue(PureWire *, uint64_t seq, PureSpan payload);
+uint64_t pure_wire_queued(const PureWire *);
+/* The last number delivered; any thread. */
+uint64_t pure_wire_delivered(PureWire *);
+/* Deliver on a thread of the wire's own, calling notify after each delivery. */
+bool pure_wire_start(PureWire *, void (*notify)(void *), void *context);
+/* Stop (a delivery under way is finished or abandoned) and free. */
+void pure_wire_close(PureWire *);
+/* Counts for a host's report. */
+void pure_wire_counts(PureWire *, uint64_t *delivered, uint64_t *attempts);
+#endif