Files
mesh-sdk/go/process/chunks.go
T
jschoubben 3f8f35a87a S14 kept chunked call: CallChunksKept and CallFileKept pace the ask and carry its id on every chunk
The assigner's compose-candidate ask is chunked, and the one-shot CallFile ended at the
first no responders; the kept call's form now makes the chunked call too.

Builds: design 47 H2 §775, H-A-405 (1), H-A-351
2026-11-22 00:55:25 +01:00

175 lines
6.9 KiB
Go

package process
import (
"bytes"
"context"
"encoding/base64"
"encoding/json"
"fmt"
"io"
"time"
"github.com/nats-io/nats.go"
"git.novox.be/novox/mesh-sdk/go/buscalls"
"git.novox.be/novox/mesh-sdk/go/calladdress"
)
// CallChunks calls a seat verb whose answer file is sent in chunks (a verb its seat definition marks `chunks`, design 47 G
// §681, A-139), the one way a process receives such an answer (A-291): it subscribes to the chunks of call (the 128 random
// bits the verb's input carries as its call) before it asks, so none is missed, asks key ("seat:<seat>.<verb>[@<node>]")
// with body as Call does, hands the verb's answer to accept (nil accepts every answer; an error ends the call before a chunk
// is taken), then receives the number of chunks the answer's member `chunks` names, in order, acknowledging each, into w.
// It answers the verb's answer. A chunk that does not come within buscalls.SeatAckWithin, or ctx ending, ends the receive.
func (c *Conn) CallChunks(ctx context.Context, key, call string, body any, accept func(answer json.RawMessage) error, w io.Writer) (json.RawMessage, error) {
return c.callChunks(ctx, key, call, "", func() (json.RawMessage, error) { return c.Call(key, body) }, accept, w)
}
// CallChunksKept is CallChunks made as a kept call (design 47 H2 §775; H-A-405): the verb is asked through the kept-call
// form (busretry.DoPaced: called again at the kept-call pace on a transport fault, ADR 0664 §1's classes, the call's own
// deadline and the kind away; one journal line per seat at the first fault, then at most once a minute), carrying ask's id
// in the header stdio.AskHeader on the call and on every chunk's acknowledgement, and stopping at ask's bound with the
// words CallKeptAsk gives (a *busretry.Unanswered naming every call). A kept chunked call carries an ask id: one naming
// none is refused before anything is published.
func (c *Conn) CallChunksKept(ctx context.Context, ask KeptAsk, key, call string, body any, accept func(answer json.RawMessage) error,
w io.Writer) (json.RawMessage, error) {
if ask.ID == "" {
return nil, fmt.Errorf("the kept call of %s names no ask id", key)
}
called, fallback, err := callSubjectsOn(key, "", c.callerToken())
if err != nil {
return nil, err
}
data, err := json.Marshal(body)
if err != nil {
return nil, err
}
asking := func() (json.RawMessage, error) {
return callKeptWith(keptOf(key, ask, nil), c.requestAsking(ask.ID), called, fallback, data)
}
return c.callChunks(ctx, key, call, ask.ID, asking, accept, w)
}
// callChunks hears the chunks of call before it asks through asking, then receives them (receiveChunks), acknowledging
// each with ask's id in stdio.AskHeader when it carries one.
func (c *Conn) callChunks(ctx context.Context, key, call, ask string, asking func() (json.RawMessage, error),
accept func(answer json.RawMessage) error, w io.Writer) (json.RawMessage, error) {
send, err := chunksOf(key, call)
if err != nil {
return nil, err
}
chunks := make(chan *nats.Msg, 4)
sub, err := c.nc.ChanSubscribe(send.Chunks(), chunks)
if err != nil {
return nil, fmt.Errorf("the chunks of %s cannot be heard: %w", key, err)
}
defer func() { _ = sub.Unsubscribe() }()
ack := func(m *nats.Msg) error {
_, err := c.nc.RequestMsg(m, buscalls.SeatAckWithin)
return err
}
return receiveChunks(ctx, key, send, chunks, ask, asking, accept, ack, w)
}
// chunksOf is the chunks of call of the seat verb key names; a key naming no seat verb, or no call, is refused.
func chunksOf(key, call string) (buscalls.SeatChunks, error) {
a, err := calladdress.Parse(key)
if err != nil {
return buscalls.SeatChunks{}, err
}
if a.Seat == "" {
return buscalls.SeatChunks{}, fmt.Errorf("%q names no seat verb, so it sends no chunks", key)
}
if call == "" {
return buscalls.SeatChunks{}, fmt.Errorf("the call of %s names no call token for its chunks", key)
}
return buscalls.SeatChunks{Seat: a.Seat, Verb: a.Verb, Call: call}, nil
}
// receiveChunks asks through asking, hands its answer to accept, then receives the number of chunks the answer's member
// `chunks` names from chunks, in order, acknowledging each through ack with a message carrying ask's id in
// stdio.AskHeader (none when empty), into w.
func receiveChunks(ctx context.Context, key string, send buscalls.SeatChunks, chunks <-chan *nats.Msg, ask string,
asking func() (json.RawMessage, error), accept func(answer json.RawMessage) error, ack func(*nats.Msg) error,
w io.Writer) (json.RawMessage, error) {
answer, err := asking()
if err != nil {
return nil, err
}
if accept != nil {
if err := accept(answer); err != nil {
return answer, err
}
}
var count struct {
Chunks int64 `json:"chunks"`
}
if err := json.Unmarshal(answer, &count); err != nil {
return answer, fmt.Errorf("%s answered no count of its chunks: %w", key, err)
}
next := func() (string, []byte, error) {
bound := time.NewTimer(buscalls.SeatAckWithin)
defer bound.Stop()
select {
case m := <-chunks:
return m.Subject, m.Data, nil
case <-bound.C:
return "", nil, buscalls.ErrSeatChunkMissed
case <-ctx.Done():
return "", nil, ctx.Err()
}
}
acked := func(subject string) error { return ack(askMsg(subject, []byte("{}"), ask)) }
if _, err := send.Receive(count.Chunks, next, acked, w); err != nil {
return answer, fmt.Errorf("the answer of %s: %w", key, err)
}
return answer, nil
}
// CallFile is CallChunks for an answer read whole, in the form a bundle's ordinary seat call answers a chunked verb (design 47
// G A-249, A-253): the verb's answer with the whole file added as its member `file` (base64), none when no chunk was sent. The
// call token is body's member `call`.
func (c *Conn) CallFile(key string, body any) (json.RawMessage, error) {
var file bytes.Buffer
answer, err := c.CallChunks(context.Background(), key, callOf(body), body, nil, &file)
if err != nil {
return nil, err
}
return withFile(key, answer, file.Bytes())
}
// CallFileKept is CallFile made as a kept call, as CallChunksKept is CallChunks's (design 47 H2 §775; H-A-405).
func (c *Conn) CallFileKept(ask KeptAsk, key string, body any) (json.RawMessage, error) {
var file bytes.Buffer
answer, err := c.CallChunksKept(context.Background(), ask, key, callOf(body), body, nil, &file)
if err != nil {
return nil, err
}
return withFile(key, answer, file.Bytes())
}
// withFile is a chunked verb's answer with file added as its member `file` (base64), none when file is empty.
func withFile(key string, answer json.RawMessage, file []byte) (json.RawMessage, error) {
var whole map[string]any
if err := json.Unmarshal(answer, &whole); err != nil {
return nil, fmt.Errorf("%s answered what is no object: %w", key, err)
}
if len(file) > 0 {
whole["file"] = base64.StdEncoding.EncodeToString(file)
}
return json.Marshal(whole)
}
// callOf is the member call of a verb's input.
func callOf(body any) string {
raw, err := json.Marshal(body)
if err != nil {
return ""
}
var in struct {
Call string `json:"call"`
}
_ = json.Unmarshal(raw, &in)
return in.Call
}