Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

New channel proposition #171

Merged
merged 13 commits into from
Feb 27, 2020
Merged

New channel proposition #171

Show file tree
Hide file tree
Changes from 3 commits
Commits
Show all changes
13 commits
Select commit Hold shift + click to select a range
099930e
updated spec with more detailed explanation of the 'default' channel
nkolba Feb 7, 2020
a72585a
some more clarifications for the 'default' channel
nkolba Feb 10, 2020
12142f7
first pass
nkolba Feb 10, 2020
f190362
fixed example syntax
nkolba Feb 10, 2020
e793d25
missed 'default' reference
nkolba Feb 12, 2020
ba3afdf
more tweaks for the global channel
nkolba Feb 12, 2020
b4d4b94
fixes from PR feedback. Cleaned example code. Return promise on lea…
nkolba Feb 12, 2020
6d6999a
add await to example
nkolba Feb 12, 2020
3f8e09d
spacing
nkolba Feb 12, 2020
4c21494
merge from upstream
nkolba Feb 19, 2020
2c5c753
clarified language for 'global' channel example
nkolba Feb 19, 2020
ff3cde4
updated 'global' example
nkolba Feb 19, 2020
87d9473
added missing methods to ts block, added a context section in block
nkolba Feb 24, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
6 changes: 3 additions & 3 deletions docs/api/DesktopAgent.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -221,7 +221,7 @@ fdc3.joinChannel(selectedChannel.id);
### `leaveCurrentChannel`

```ts
leaveCurrentChannel() : <void>;
leaveCurrentChannel() : Promise<void>;
```

Removes the app from any channel membership. Context broadcast and listening through the top-level `fdc3.broadcast` and `fdc3.addContextListener` will be in a no-op when the app is not on a channel.
Expand All @@ -231,9 +231,9 @@ Removes the app from any channel membership. Context broadcast and listening th

```js
//desktop-agent scope context listener
const fdc3Listener = fdc3.addContextListener(context => {});
const fdc3Listener = fdc3.addContextListener(context => {});

fdc3.leaveCurrentChannel();
await fdc3.leaveCurrentChannel();
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Why is this now asynchronous?

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I suggested that based on the fact that joinChannel being asynchronous. It could be useful to know when the leave operation successfully completed (or not).

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@vmehtafds @nkolba I don't understand why this requires it to be asynchronous. success/error reporting is not the same thing as long-running operations that need to be asynchronous.

If you call the method without an exception, it worked. If it throws an exception, it didn't. If leaving (or joining) a channel as implemented in anything more then O(1) time, the implementation is doing something very weird.

I think making this operation asynchronous adds unnecessary complexity and ambiguity, and is a mistake.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@rikoe @vmehtafds . I'm in favor of keeping things simple.
Given that joinChannel is async - I was thinking symmetry and consistency (most other methods are async). However, there is definitely a good case to be made for keeping it sync.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is joinChannel async? 🤔 I would argue the same applies. I do agree that both join and leave should both be consistent though...

Arguably both join and leaving channels should be instant no-ops, but happy to go with the majority view here.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I could see wanting to do this:

await fdc3.joinChannel('global');
fdc3.broadcast(context);

//the fdc3Listener will now cease recieving context

//listening on a specific channel though, will continue to work
Expand Down
8 changes: 4 additions & 4 deletions docs/api/api-spec.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -166,15 +166,15 @@ The 'global' channel should be returned as part of the response from the `fdc3.g
An app gets the current context of the `global` as a fallback if no other context is set.
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I am not sure what this means? Can you expand on what you mean by a fallback?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

some platforms may have a tiered approach, where there is a global context (maybe coming from a top-level search) and more localized contexts created with channels. In that case, if an app doesn't have a context coming from a specific channel it is joined to it may want to pull the global context.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I am tempted to say this is slightly inconsistent with the rest of the behaviour, and therefore introduces a bit of confusion. I think channels should always work the same way, regardless of what context it is. If you are on no channel, no context will be recorded. If you want context to be recorded, join a channel.

In this particular case I would prefer if the spec doesn't mention this behaviour. Someone can still do this if they like, as the standard wouldn't explicitly forbade it, but I don't personally think it makes much sense.

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I agree with @rikoe here. I feel we are kind of reintroducing a new special behavior for "global" with this wording.

The way I expect - If I join global channel and also add a explicit channel.contextListener for red channel, I am expecting to get messages from both. Your statement seems to suggest you will only receive red channel messages (not sure if that is what you meant) and I will fallback to global when I remove the listener for red channel.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@rikoe , @vmehtafds - some clarifications:

  1. in the proposal, the "global" channel would NOT have any special behavior, it would work just like any other channel. The only thing special about it, would be that it is a reserved system channel name so that: platform owners could choose to start apps on global by default, app developers could choose to start their apps on global by default, app developers could choose to listen to and broadcast to the global channel, etc. These would all be opt-in behaviors.
  2. in the code example, yes, if you joined red and added a contextListener on global, you would get messages for both. I am not dictating only using global as fallback - that was just an example of what I think is a probable use-case (I could be wrong)

@rikoe I am not clear on the concerns (I don't see how this is going against channels always working the same) but I am fine changing this example to something else. Do you have any suggestions?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@nkolba I see what you mean now - adding an explicit listener to global. No other concerns with what you describe.

However, An app gets the current context of the global as a fallback if no other context is set. is confusing.

The language here indicates special fallback behaviour without having to set up extra explicit listeners, which is unexpected.

If you are joined to global, getCurrentContext should get you the context on global, if not, you will get nothing. I think it will be clearer if we just remove the word "fallback" everywhere.

Of course you can still directly retrieve the channel itself and listen/retrieve the context on it, but that is a separate workflow from the join channel one.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@rikoe . Yes, if you are joined to global, then fdc3.getCurrentContext only gets you context from global - nothing in the example contradicts that. The example is attempting to show both using fdc3.joinChannel and directly retrieving channels and setting explicit listeners. I'll try to make the language and the example clearer.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Change
An app gets the current context of the global as a fallback if no other context is set.
to
An app can retrieve the context on the global channel by accessing it directly, regardless if it is currently "joined" to the global channel or not.
Or something like that...

If you want to make it even more clear:

// retrieve current fdc3 context
const context = await fdc3.getCurrentContext("fdc3.instrument")
// context is null, as not currently joined to a channel

const globalChannel = await fdc3.getSystemChannels.filter(c => c.id === "global")
const globalContext = await fdc3.getCurrentContext("fdc3.instrument")
// context is instrument AAPL on the global channel

fdc3.joinChannel('global')
const context = await fdc3.getCurrentContext('fdc3.instrument')
// top-level context is now instrument AAPL as well because we have joined the global channel

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@rikoe just pushed some language cleanup

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@rikoe updated example pushed


```js
let gChan = await fdc3.getOrCreateChannel("global");
let ctx = await gChan.getCurrentContext("fdc3.instrument");
const globalChannel = await fdc3.getOrCreateChannel("global");
const context = await globalChannel.getCurrentContext("fdc3.instrument");
```

An app wants to respond to all context changes, whether on a joined channel or the `global` channel.
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I also don't understand what is sentence mean and what feature/behavior the below example demonstrates. Can you just expand a bit?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@vmehtafds . This example is showing an app listening to the global channel outside of whatever channel it may be joined to. This example is meant to illustrate context scopes - i.e. I may have a joined channel scope and a global scope. For example, in a multi-windowed application, I may have a top-level search bar that represents global scope and individual windows may be on their own individual context scopes, or joined to a channel-wide context scope. This may or may not be useful for you. I am happy to get other examples in addition to or instead of this one.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I agree with @vmehtafds here: An app wants to respond to all context changes, whether on a joined channel or the global channel.

This is very confusing to me.

  • If you are joined to the global channel, you will get its context changes.
  • If you are joined to the red channel you will get its context changes.
  • If you are joined to no channels you will get no context changes.

I think this idea of scoping etc. is unnecessary complexity at this stage and I don't believe it was something originally in the spec, or proposed before. We should just make channels mutually exclusive.

If you do want this type of behaviour (which I think is unnecessary), it should be done by passing an array of channel names to join, and further API support for figuring out how channels are scoped/which "set" of channels you are in.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@rikoe @vmehtafds
"Channel scoping" is not something proposing for the spec - its something that someone may (or may not) implement on top of it. This is meant to be an implementation example.

This example seems to be confusing and taking us down a rabbit hole. I'm happy to get other suggestions of how to illustrate the API.

Copy link
Contributor

@rikoe rikoe Feb 19, 2020 •
edited

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Change An app wants to respond to all context changes, whether on a joined channel or the global channel. to: An app wants to explicitly receive context events on the global channel, regardless of what channel it is currently joined to (if any). (Or something like that. Apart from that the example is fine.)

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@rikoe @vmehtafds - just pushed some clarifications to the language on this example. Please keep the feedback coming!


```js
let gChan = await fdc3.getOrCreateChannel("global");
let listener = gChan.addContextListener(contextListener);
const globalChannel = await fdc3.getOrCreateChannel("global");
const listener = globalChannel.addContextListener(contextListener);
```

### Direct Listening and Broadcast on Channels
Expand Down