[Docs] Unclear how the bidirectional communication should work

[c43721]

Heya, neat library. Almost what I was asking for just a day ago 😆

I'm having a hard time understanding how to achieve bidirectional communication. It's almost worded like you can just push data back to the client, but I think that's not the right kind of thinking. So I dug deeper I ended up using the functionality that allows you to pass functions by reference- it seems like this is kind of what's intended?

Where it gets really confusing when you add things like timers into the equation. Without marking the method as async and awaiting a promise directly, it doesn't behave as you'd expect (from a "nieve" point of view, that is.)

I have an example repository you can use to explore this in more depth

Example client:

using wsApi = newWebSocketRpcSession<MyWs>("ws://localhost:8000");

const d = (sm: string) => console.log("got something: " + sm)

const wsResult = await wsApi.test(d);

console.log(wsResult);

Example websocket "client":

class WsServer extends RpcTarget {
    async test(fn: (data: string) => void) {
        fn("testing");

        setTimeout(1000, () => {
            fn("hello from timeout");
        });

        return true;
    }
}

It'll call the first function, then return true. That makes a lot of sense! I would expect this to be a "gotcha" here and not a bug of the protocol (how would you know timers are involved?)

Now replace the setTimeout with an import from node:timers/promises:

class WsServer extends RpcTarget {
    async test(fn: (data: string) => void) {
        fn("testing");

        const msg = await setTimeout(1000, "da");
        fn(msg);

        return true;
    }
}

We'll get what we want:

got something: testing
got something: da
true

The ask here is if we can get some examples of bidirectional communication and the "gotchas" those comes with. I can see how functions can be used to achieve the "notification" style API for a client and this is something I'm looking to explore :)

[kentonv]

The setTimeout() version actually works fine -- it's just that the callback happens after test() has returned. If you change your client code to wait long enough, you'll see the call still happens, asynchronously. Of course, if you ran the some code locally without the RPC system in the middle, you'd get the same behavior.

I agree we could use more examples of callbacks. But there aren't very many "gotchas", it mostly just works exactly like a local callback would.

[vilvei]

Hi, Capnweb looks very promising. But I have the same issue than then OP. Callback function does not work when calling from server after timeout/interval.

It does nothing or when awaiting it, it throws Error "Attempted to use RPC stub after it has been disposed". When not awaiting, the return value is

[object Function]

Example nodejs-server:

import { createServer } from "node:http";
import { WebSocketServer } from 'ws';
import { RpcTarget, newWebSocketRpcSession } from "capnweb";

class TheApi extends RpcTarget {
  constructor() {
    super();
  }
  async hello(msg) {
    return `hello ${msg}`;
  }

  async setCallback(cbfunc) {
    this.timercalls = 1;
    this.cbfunc = cbfunc;
    this.timer = setInterval(this.doStuff.bind(this), 2000);
    const retval = await this.cbfunc(`server ${this.timercalls}`);
    console.log(`cbfunc returnvalue: ${retval}`);
  }

  async doStuff() {
    if (this.cbfunc) {
      ++this.timercalls;
      console.log(`calling cbfunc ${this.timercalls}`);
      const retval = this.cbfunc(`server ${this.timercalls}`);
      // const retval = await this.cbfunc(`server ${this.timercalls}`);
      console.log(`cbfunc returnvalue: ${retval}`);
    }
  }
}


let httpServer = createServer();
let theApi = new WebSocketServer({noServer: true});

theApi.on('connection', ws => {
  newWebSocketRpcSession(ws, new TheApi());
})

httpServer.on('upgrade', (request, socket, head) => {
  const {pathname} = new URL(request.url, 'ws://base.url');
  if (pathname === '/theapi') {
    theApi.handleUpgrade(request, socket, head, ws => {
      theApi.emit('connection', ws, request);
    });
  }
  else {
    socket.destroy();
  }
})
httpServer.listen(19552);

Example nodejs-client:

import { RpcTarget, newWebSocketRpcSession } from "capnweb";

let api = newWebSocketRpcSession("ws://127.0.0.1:19552/theapi");
let result = await api.hello("World");
console.log(result);

function cbf(msg) {
  console.log(`msg: ${msg}`);
  return true;
}
api.setCallback(cbf);

setInterval(() => {
  console.log('waiting');
  cbf('client n');
}, 5000);

when NOT awaiting, the call produces [Object Function]

const retval = this.cbfunc(`server ${this.timercalls}`);
==>
cbfunc returnvalue: [object Function]

When awaiting, it throws

const retval = await this.cbfunc(`server ${this.timercalls}`);
==>
new Error("Attempted to use RPC stub after it has been disposed.")

So maybe there could be one simple example how to use server to client calling by function reference. Thanks!

[kentonv]

@vilvei Be sure to read the part of the readme that talks about disposal rules.

In particular, the cbfunc parameter passed to your setCallback() will be disposed as soon as setCallback() returns. If you want to hold onto it longer than that, you need to .dup() it.

   async setCallback(cbfunc) {
     this.timercalls = 1;
-    this.cbfunc = cbfunc;
+    this.cbfunc = cbfunc.dup();
     this.timer = setInterval(this.doStuff.bind(this), 2000);
     const retval = await this.cbfunc(`server ${this.timercalls}`);
     console.log(`cbfunc returnvalue: ${retval}`);
   }

[yunfan]

its the same question came to my mind when i read the official blog's introduction of capnweb
since it claims

Supports bidirectional calling. The client can call the server, and the server can also call the client.

but sooner the article just ended after some quick example , but still where is the example showing this claim?
so i came to the repo here, unfortunately there were also none of these in the poorly examples directory

i think its quite an important feature in this modern age, so i am willing to see this issue sooner be in fixed

[vilvei]

@yunfan The actual issue is with documentation and examples. The dup-functionality is explained, but not well connected with bidirectional calling. So when I first read the whole doc, I saw the thing, but later when I came back to actually do something with the callbacks, I totally forgot the dup, and documentation doesn't offer the solution for somebody skimming fast.

[balazskosi]

You can do bidirectional calling without supplying callbacks from the client.

When you create the rpc session you can pass in a localMain on both sides. e.g when you connect to the server, you pass in the client api.

const serverApi = newWebSocketRpcSession<ServerApi>("ws://localhost:8001/connect", new ClientApi());

And when you create the session on the server side, then you get the stub pointing to the this api created on the client side.

const clientApi = newWebSocketRpcSession<ClientApi>(ws, new ServerApi());