new AutobahnJS API

#1

Hi,

I have started API docs for the new AutobahnJS (with WAMPv2 support):

https://github.com/tavendo/AutobahnJS#api

For my taste, the API looks good, but any feedback is welcome!

So if you have ideas/objections rgd AutobahnJS new API, please comment now, since we want to freeze it soon ..

Cheers,
/Tobias

0 Likes

#2

A quick scan through session.js made me wonder why received data is “filtered” before provided to handlers. For example, the result of a call is passed to the handler either as a single arg or a Result, but in both cases the details are lost. Deciding whether to use a single arg or to construct a Result is extra work before the handler is called and requires extra work in the handler to distinguish between single arg and Result. Another example is Event where the handler is called with args, kwargs and ed=Event which only contains the publication and publisher, but other details are not available in the handler.
To allow for extensions and easy matching of handlers and messages, why not call the handlers with the all available data from the messages? For example, receiving event [EVENT, subscriptionId, publicationId, details], args], kwargs] and than call a handler like handler(subscriptionId, publicationId, details, args||[], kwargs||{}) or event handler(EVENT, subscriptionId, publicationId, details, args||[], kwargs||{}), allowing generic handlers (intercepting, logging, etc).

my 2 cents

renej

ps I really think that v1->v2 is a big step forward

···

Op vrijdag 14 februari 2014 16:46:20 UTC+1 schreef Tobias Oberstein:

Hi,

I have started API docs for the new AutobahnJS (with WAMPv2 support):

https://github.com/tavendo/AutobahnJS#api

For my taste, the API looks good, but any feedback is welcome!

So if you have ideas/objections rgd AutobahnJS new API, please comment
now, since we want to freeze it soon …

Cheers,

/Tobias

0 Likes

#3

Why is it that Session.subscribe() overwrites previous subscriptions? If I want multiple components listening to a single event, do you demand multiple websockets? Am I supposed to do my own (easy-to-hang) event routing in my subscription handler? What's the rationale there?

This https://github.com/tavendo/AutobahnJS#active-subscriptions is misleading, since it looks like you should be able to paste in that line and have it work, which you can't since it's accessing the class. Also, since the API is changing rapidly, could you document what version each object was added or removed in? In 0.9.0-3 this array doesn't exist.

-Nick Guenther
4B Stats/CS
University of Waterloo

···

On Fri, Feb 14, 2014 at 10:46 AM, Tobias Oberstein <tobias.o...@gmail.com> wrote:

Hi,

I have started API docs for the new AutobahnJS (with WAMPv2 support):

https://github.com/tavendo/AutobahnJS#api

For my taste, the API looks good, but any feedback is welcome!

So if you have ideas/objections rgd AutobahnJS new API, please comment now, since we want to freeze it soon ..

0 Likes

#4

Also, why do you mix promises and traditional js handlers? Why is there Connection.onopen but subscription.unsubscribe().then( ... ) ? Why not just Connection.open().then( function(session) { ... } )?
Also, if connections and sessions are 1:1, why not conflate them into one type?

Sorry for nagging now, after you've frozen it, but I hadn't the time to get too dirty with Autobahn (and I still don't, not really).

···

On Mon, Feb 24, 2014 at 11:04 PM, Nick Guenther <ngue...@uwaterloo.ca> wrote:

On Fri, Feb 14, 2014 at 10:46 AM, Tobias Oberstein > <tobias.o...@gmail.com> wrote:

Hi,

I have started API docs for the new AutobahnJS (with WAMPv2 support):

https://github.com/tavendo/AutobahnJS#api

For my taste, the API looks good, but any feedback is welcome!

So if you have ideas/objections rgd AutobahnJS new API, please comment now, since we want to freeze it soon ..

Why is it that Session.subscribe() overwrites previous subscriptions? If I want multiple components listening to a single event, do you demand multiple websockets? Am I supposed to do my own (easy-to-hang) event routing in my subscription handler? What's the rationale there?

This https://github.com/tavendo/AutobahnJS#active-subscriptions is misleading, since it looks like you should be able to paste in that line and have it work, which you can't since it's accessing the class. Also, since the API is changing rapidly, could you document what version each object was added or removed in? In 0.9.0-3 this array doesn't exist.

0 Likes

#5

And on a similar theme: if you're going to make realms and connections 1:1, please provide a shortcut like this: connection.open("my_realm").
Actually, I would prefer if a connection couldn't change its realm if realms and connections are going to be 1:1, but I understand that there might be an edge case where a single connection hops between realms for some reason (though, I would rather handle that with two orthogonal connections, sharing information through messaging each other, not by internally sharing state)

···

On Mon, Feb 24, 2014 at 11:27 PM, Nick Guenther <ngue...@uwaterloo.ca> wrote:

On Mon, Feb 24, 2014 at 11:04 PM, Nick Guenther > <ngue...@uwaterloo.ca> wrote:

On Fri, Feb 14, 2014 at 10:46 AM, Tobias Oberstein >> <tobias.o...@gmail.com> wrote:

Hi,

I have started API docs for the new AutobahnJS (with WAMPv2 support):

https://github.com/tavendo/AutobahnJS#api

For my taste, the API looks good, but any feedback is welcome!

So if you have ideas/objections rgd AutobahnJS new API, please comment now, since we want to freeze it soon ..

Why is it that Session.subscribe() overwrites previous subscriptions? If I want multiple components listening to a single event, do you demand multiple websockets? Am I supposed to do my own (easy-to-hang) event routing in my subscription handler? What's the rationale there?

This https://github.com/tavendo/AutobahnJS#active-subscriptions is misleading, since it looks like you should be able to paste in that line and have it work, which you can't since it's accessing the class. Also, since the API is changing rapidly, could you document what version each object was added or removed in? In 0.9.0-3 this array doesn't exist.

Also, why do you mix promises and traditional js handlers? Why is there Connection.onopen but subscription.unsubscribe().then( ... ) ? Why not just Connection.open().then( function(session) { ... } )?
Also, if connections and sessions are 1:1, why not conflate them into one type?

0 Likes

#6

Nick,

Why is it that Session.subscribe() overwrites previous subscriptions? If
I want multiple components listening to a single event, do you demand
multiple websockets? Am I supposed to do my own (easy-to-hang) event
routing in my subscription handler? What's the rationale there?

Not sure what you mean. Attaching multiple client-side event handlers to one and the same subscription?

If so, we could provide this like so:

function handler1(args, kwargs, details) { ... }
function handler2(args, kwargs, details) { ... }

session.subscribe('com.myapp.topic1').then(
    function (subscription) {
       subscription.watch(handler1);
       subscription.watch(handler2);
    }
);

Essentially, the following 2 would be equivalent

session.subscribe('com.myapp.topic1', handler1);

and

session.subscribe('com.myapp.topic1').then(
    function (subscription) {
       subscription.watch(handler1);
    }
);

The difference is: the latter form allows to attach multiple event handlers to one and the same subscription.

I have added an issue: https://github.com/tavendo/AutobahnJS/issues/54

If you care, please leave your suggestions/comments there ..

This https://github.com/tavendo/AutobahnJS#active-subscriptions is
misleading, since it looks like you should be able to paste in that line
and have it work, which you can't since it's accessing the class. Also,

Ok, I've adjusted the notation and added examples

https://github.com/tavendo/AutobahnJS#active-subscriptions
https://github.com/tavendo/AutobahnJS#active-registrations

since the API is changing rapidly, could you document what version each
object was added or removed in? In 0.9.0-3 this array doesn't exist.

Sorry for the inconvenience ..

/Tobias

···

-Nick Guenther
4B Stats/CS
University of Waterloo

0 Likes

#7

Also, why do you mix promises and traditional js handlers? Why is there
Connection.onopen but subscription.unsubscribe().then( ... ) ? Why not
just Connection.open().then( function(session) { ... } )?

Because a connection can become open multiple times (upon automatic reconnection .. which is not yet migrated to new code, but will). upon reconnection, the onopen() will fire again, but with a new session object.

A subscription can only be unsubscribed once.

In essence: we use promises when something occurs once, and callbacks when something can occur multiple times.

The exception to this rule is: progressive call results. These are signaled via promise "progress". This is non-standard whenjs specific, and .. uses a callback on the promise object.

Also, if connections and sessions are 1:1, why not conflate them into
one type?

Because they are not really 1:1. A session runs _over_ a connection. The session can end, and another session become open, on the same underlying connection. However, there can be at most 1 session active on a given connection at any given moment.

Sorry for nagging now, after you've frozen it, but I hadn't the time to
get too dirty with Autobahn (and I still don't, not really).

Don't worry, and please continue to nag;) We can still change/fix some things now. So if you have more suggestions, yes please!

/Tobias

0 Likes

#8

And on a similar theme: if you're going to make realms and connections
1:1, please provide a shortcut like this: connection.open("my_realm").
Actually, I would prefer if a connection couldn't change its realm if
realms and connections are going to be 1:1, but I understand that there

mmh. I guess I can't follow .. can you explain?

"realms and connections" are different things.

"sessions and connections" aren't really 1:1.

the current code does not allow to hop between realms on a single connection:

https://github.com/tavendo/AutobahnJS/blob/master/package/lib/connection.js#L45

···

might be an edge case where a single connection hops between realms for
some reason (though, I would rather handle that with two orthogonal
connections, sharing information through messaging each other, not by
internally sharing state)

0 Likes

#9

A quick scan through session.js made me wonder why received data is
"filtered" before provided to handlers. For example, the result of a
call is passed to the handler either as a single arg or a Result, but in
both cases the details are lost. Deciding whether to use a single arg or
to construct a Result is extra work before the handler is called and
requires extra work in the handler to distinguish between single arg and

Promises can be resolved/rejected only with exactly 1 value. So if the result is "complex" (that is, has more than 1 positional result and/or has keyword results), the result must be wrapped (into an object of Result).

The details from the WAMP call result message are indeed used

https://github.com/tavendo/AutobahnJS/blob/master/package/lib/session.js#L637

but not forwarded to the user code (consuming the single-valued result).

However, we might have:

https://github.com/tavendo/AutobahnJS/issues/55
https://github.com/tavendo/AutobahnJS/issues/56

If you care, please comment there ..

Result. Another example is Event where the handler is called with args,
kwargs and ed=Event which only contains the publication and publisher,
but other details are not available in the handler.
To allow for extensions and easy matching of handlers and messages, why
not call the handlers with the all available data from the messages? For
example, receiving event [EVENT, subscriptionId, publicationId,
details], args], kwargs] and than call a handler like
handler(subscriptionId, publicationId, details, args||[], kwargs||{}) or
event handler(EVENT, subscriptionId, publicationId, details, args||[],
kwargs>>{}), allowing generic handlers (intercepting, logging, etc).

I can see your point, but it's a deliberate design: minimal API, hiding of internals, ..

That being said, and regarding details from EVENTs: if there are more details interesting to user code, we can add those to Event class without changing signature of event handlers.

my 2 cents
renej

ps I really think that v1->v2 is a big step forward

Thanks for feedback! If you have more, please feel free ..

/Tobias

···

Am 19.02.2014 14:30, schrieb renej:

Op vrijdag 14 februari 2014 16:46:20 UTC+1 schreef Tobias Oberstein:

    Hi,

    I have started API docs for the new AutobahnJS (with WAMPv2 support):

    https://github.com/tavendo/AutobahnJS#api
    <https://github.com/tavendo/AutobahnJS#api>

    For my taste, the API looks good, but any feedback is welcome!

    So if you have ideas/objections rgd AutobahnJS new API, please comment
    now, since we want to freeze it soon ..

    Cheers,
    /Tobias

--
You received this message because you are subscribed to the Google
Groups "Autobahn" group.
To unsubscribe from this group and stop receiving emails from it, send
an email to autobahnws+...@googlegroups.com.
For more options, visit https://groups.google.com/groups/opt_out.

0 Likes