handle

Handle one batch, which is never empty.

Returns how far the batch was handled, which is what allows a handler to make progress it does not have to repeat:

• ok(none) — the whole batch. The provider commits past its last record.
• ok(some(offset)) — handled through offset inclusive, and no further. The provider commits past that one and redelivers the rest. A handler that processes seven of ten records can keep the seven instead of failing the batch and being given all ten again.
• error — none of it was handled. See handler-error.

An offset outside the batch is a caller error and the provider treats it as error: committing past records it never delivered would drop them.

async because the provider awaits the result before committing, and because a handler that does real work needs somewhere to await its own imports from.