refactor: Rename WithChannels, tx and rx

[Frando]

We have some reports that the WithChannels { tx, rx, inner } terminology is not very intuitive for people.

This very-much-breaking PR proposes the following renames:

• WithChannels { inner, tx, rx, span } becomes Request { message, reply, updates, span }
• Request is renamed to RequestSender (to be able to use Request for what was so far WithChannels)
• derive arguments are updated accordingly: tx -> reply, rx -> updates

Let's discuss! We only wanna do this once.

cc @b5

[rklaehn]

Hm, the whole thing is the request, the inner thing is the message. But then I call the messages XXXRequest usually, e.g. GetRequest, PutRequest. Still, this part doesn't seem so controversial.

About rx/tx vs update/reply. It's longer and deviates from the async rust convention of tx/rx. Is it really that important that this is intiuitive vs short, given that it is intentionally pretty low level to match what you would do by hand?

I guess @b5 should comment. You are the target audience for this lib. If you find it much better I guess we should do it.

[b5]

I'm a big fan of updates as the word for streaming responses, but I think Request.reply should be Request.response, ditto for the derive tx -> reply, which I think should be tx -> response.

The struct being called Request, and a field of that struct containing a response does feel kinda strange. Generally I find this within "shrugging distance" that could be explained with a clarifying comment, but I think I need to play with implementing from this branch to be sure. Will try to run an experiment at some point in the next week & report back here.

To me any struct that's called Request should generally be the output of some sort of builder pattern, where I construct a request & call some kind of do on it, usually passing it to a Client that actually executes the request, and returns a new struct that defines the response, or a stream of responses.

[Frando]

I think I agree to what @b5 said, but also to the niceness of short names for these oftenly-destructured structs that @rklaehn brings up. Let's go back to the bikeshed board:

// status quo
let WithChannels { inner, tx, rx, span } = msg;

// frando's first suggestion
let Request { message, reply, updates, span } = request;

// b5's first suggestion
let WithChannels { request, response, updates, span } = msg;

I'm unsure myself. WithChannels always felt a bit weird for me, but I agree that Request is also imperfect. Any other ideas on what to call the "struct that contains the initial request message, and the streams for responses and updates from the client"?

So here's some more variations

let Incoming { request, tx, rx, span } = msg;
let ReqCtx { message, tx, rx, span } = ctx;
let Rpc { msg, res, req, span } = rpc;

[rklaehn]

Ok, let's see.

span is clear.
I like calling the message request, since really the first message is what determined what kind of request we want to do. I think msg or message is too generic. This is message passing. Everything is a message.

I also like updates. In many cases it won't be needed, so if we don't want to do rx I think it is the best option.

response/reply I am not so sure. request is a message, the actual request. response is not the response, but a channel to send 0, 1, or n responses. For a field called response I would expect something like assigning to it req.response = 1.

So I don't hate reply.

Regarding WithChannels, yeah, never really liked the name myself, but it is just what it does, it is a request with channels. So maybe RequestContext or ReqCtx?

So for me the current best alternatives are

Short:

ReqCtx { req, rx, tx, span }

Long:

RequestContext { request, updates, reply, span }

In the context of this kind of rust programming with channels, rx and tx are well established names that for me aren't that bad, tbh.

[Frando]

I think I like ReqCtx { req, rx, tx, span } too.
I kinda also like Rpc { req, rx, tx, span } - Rpc is "remote procedure call", and this is what makes up a remote procedure call, no?

@b5 do you think rx and tx will work, or are still more attached to other names for the channels?

[Frando]

Thinking again: What aboutMessage { req, rx, tx, span }?

This fits nicely to the naming we usually do:

#[rpc_requests(FooService, message = FooMessage)]
enum FooProtocol {
  #[rpc(tx = spsc::Sender(String)]
  Get(String)
}

    async fn handle(&mut self, msg: StorageMessage) {
        match msg {
            StorageMessage::Get(get) => {
                info!("get {:?}", get);
                let Message { tx, req, .. } = get;
                tx.send(self.state.get(&req).cloned()).await.ok();
            }
        }
    }

[matheus23]

I know this is super bikesheddy now, but I personally really like the "request, updates, reply, span" terms a lot more than "tx, rx" terminology.
I don't really know what "tx" stands for, and in the context of RPC requests even I have trouble remembering which one is which between tx and rx.

I think after reading all the proposals, I'd go for ReqCtx { request, updates, replies, span } (where I'd replace reply with replies to match updates EDIT: Perhaps that's misguided as it can be a single reply, and that's the more common case? in that case ignore).

FWIW I'm also totally fine with shortening request to req, I just don't find it as aesthetically pleasing as it wouldn't match the other nouns not being shortened. But there's no understanding issue for that one. I really only feel strongly about not using tx or rx and really liking updates and replies as those are immediately obvious to me.

[dignifiedquire]

reply is very odd and reads to me as if someone forgot the word for response 😅

[matheus23]

response/responses is also a good IMO.