Re-Structure preview

[SunFulong]

Hello, this PR have no content modify, only re-structures.

IMO, some chapters in current basic profile should extract out to the protocol spec level, so I moved them out, and move old "Basic Profile" title before "Message Definitions".

This is just a preview to discuss, if accept, I will rename BP files from 01.

[oberstet]

Thanks for thinking about overall "structure" of the spec text! Improving readability and comprehensibility for new implementors is quite important! And a fresh, new look as you can bring to the table plus actual concrete proposals for improvements (as in this PR) is highly welcome!

As far as I see, this PR is really "only" restructuring existing contents - neither removing or adding any contents. Highly welcome, I appreciate, and to me, it looks like an improvement (and my problem in judging is likely anyways that I cannot have an independent fresh look anymore .. obviously)

So let's see what others say;)

[SunFulong]

@oberstet Unfortunately, I'm not a native English speaker and writing content in English looks very unprofessional. We have also discussed some details before, such as adding additional algorithms to the CRA chapter. I also tried to write it, but finally gave up.

Therefore, the work I can do is probably correct errors, make minor adjustments to the content and structure, and come up with some new ideas.

[oberstet]

I also tried to write it, but finally gave up.

don't worry, I am pretty sure we can collaborate, I could improve english text / language to some point (not a native speaker also), and there are a few native english speakers in the WAMP implementors community which might chime in as well .. just saying .. pls don't hesitate to come up with text if you feel sth is missing or what ..

[SunFulong]

In my work, I have already used the WAMP protocol in production projects, across WEB(PWA), App(navite) and Backend, and the router and client were all implemented from scratch. I have used Python, JavaScript, and now I am using Rust language for implementation.

As a private request, if you could add my name to the list of contributors, it would make it easier for me to promote this protocol among my social circles.

[oberstet]

from my perspective, sure! pls see #520

[KSDaemon]

I had a quick look: well — why not. Maybe it will be clear. It is important not to loose any parts during movements. So @SunFulong If you'd like — please go ahead with restructuring and let's discuss the PR Ready version.

[Jopie64]

@SunFulong

Unfortunately, I'm not a native English speaker and writing content in English looks very unprofessional.

Not sure whether it is accessible in China, but I seriously think ChatGPT could help here. 😊 Just try to ask it to translate your Chinese text into professional English RFC-ready text.

[SunFulong]

Not sure whether it is accessible in China

The answer is NO, the ChatGPT blocks access from China, but Google Translate works.

[SunFulong]

@oberstet @KSDaemon Please review this version.

[oberstet]

@oberstet @KSDaemon Please review this version.

ok, I have reviewed the changes in a "skim-over" fashion (means, not "word by word"), and it seems to contain exclusively editorial changes - no contents is removed, no new contents added, right?

rgd the re-orderings applied: this seems good to my eyes and an improvement.

there is 1 exception, which IMO could be discussed or have had different views or perspectives about:

"Basic vs Advanced Profile"

this PR moves this into some sub-sub section, after "websocket" and other things.

I would say: this is a "top-level topic", as it explains to a reader why there are actually two specs

IMO this should be discussed .. I am not overly stuck on this aspect. the existing ordering, I'd be fine with reordering as well ...

[SunFulong]

no contents is removed, no new contents added, right?

Almost, changed some accidentally markdown tag, e.g. *Caller*s to *Callers*.

In fact, I want to make structural like this:

• Profiles
  • BP vs AP
  • Basic Profile
    • Messages
    • Session
    • etc
  • Advanced Profile
    • Messages
    • Session
    • etc

But, the level is too deep, so let the BP and AP as top-level, messages which follows the BP or AP as sub-level, the rest as top-level. Then I moved BP vs AP to Introduce chapter.

Don't you think if using BP vs AP, BP, AP as chapter separator is something strange?

[KSDaemon]

++ for the "WAMP in a nutshell" :)

[oberstet]

would that work?

• Part 1, 2 and 3: https://wamp-proto.org/wamp_latest_ietf.html
• Part 1 and 2: https://wamp-proto.org/wamp_bp_latest_ietf.html
• Part 1 and 3: https://wamp-proto.org/wamp_ap_latest_ietf.html

---

I'd also be fine with only keeping the one full version

• Part 1, 2 and 3: https://wamp-proto.org/wamp_latest_ietf.html

A reader might just stop reading before part 3 AP ...

[SunFulong]

The full spec is not a final delivery

I mean, not a final submit to IETF, but separated BP and AP is if we still plan to submit.

[KSDaemon]

@SunFulong if you're saying about the difference in headers levels — that can be fixed during the build process.
I don't mind about having only one full spec as @oberstet suggests. But in that case, it will be hard to submit only basic profile to IETF as a separate document.

[oberstet]

but separated BP and AP is if we still plan to submit.

IETF .. OASIS .. it would be nice! the latter could be easier, not sure. but hey, lots of talking and admin stuff just to get a RFC number? wtf, I have code to write;)

also, from my PoV, an

• automated testsuite for WAMP, plus
• automated tests and reports publishing on the WAMP website

cross-testing all implementations (both router and client) X all WAMP features would be much more important, useful and effective for users!

an RFC is just another ASCII file ...

[SunFulong]

See current push, I inserted HARD PART TITLE in full spec only

[KSDaemon]

Let's fix the ToC levels now?

[SunFulong]

Let's fix the ToC levels now?

Current build scripts won't fine for both separate and combined specs.

Let's do a final confirm, do we really downgrade profile part content level?

[KSDaemon]

Also BP and AP don't look great now.

Introduction → Introduction

[SunFulong]

Introduction → Introduction

Tried over and over, my best idea is change first Introduction to About, how do you think?

[oberstet]

uuh, lots of thoughts, attempts .. bit of chaos;)

first, let me preface: don't worry! this is pretty normal and expected. agreeing on anything between people, diverse as this group, coming from different backgrounds, having different focus and interests, is never easy and requires effort.

naturally. the hassles are unavoidable. fwiw, what we experience here is nothing compared with what there was in WebSocket IETF WG ;)

---

I tried to take a step back and focus on what we can agree on, and figure out a concrete proposal for that only.

of course not coming up with a "full proposal" for "everything" is a risk (later on, adding the parts taken out of focus for now might have ramifications upon the already "done" initial part"). well, that's life;) take risks.

anyways, what I think we agree on (pls correct me / add as you see fit):

• we want one self-contained document for the BP contents only, and
• this document should only lay out the bare essentials ("minimum viable") of WAMP, and
• make it quick & easy for a potential implementer or newcomer to enter, and
• that one document should be formatted in a way so we have the option to submit it to IETF or OASIS

based on these goals, and also trying to take into account the other things we discussed (terminology, "in a nutshell"), and also some changes that appear to be desirable for me (from taking a step back and with a new look), here is my proposal for structure of above document (only first couple of TOC levels - sub-sub-sections should then be sorted in):

[KSDaemon]

Okay. I played a bit with it. And got to this point:

• All 3 docs have their abstracts (the difference is in adding profile names to BP/AP docs)
• BP and AP have their own introduction sections that are not copy/pasted to anywhere else.
• Only the full document has next sections:
  • WAMP in a Nutshell
  • Basic vs Advanced Profile
• BP and AP in the full spec are big top-level sections having all their details inside

The one question I still have in mind is the place for WAMP in a Nutshell section: I put it into full spec, but it might look better in BP/Introduction Section...

If this looks good — I can push this for review (probably in other PR)

Here are screenshots of how it looks now.

[oberstet]

If this looks good — I can push this for review (probably in other PR)

mmmh, for my eyes, tbh, I don't think this is an improvement over the current text:(

E.g. "Abstract" for me is the same as "WAMP in a nutshell" and "BP vs AP" is an administrative frontmatter which should be outside the TOC.

In general, IMO we should only concentrate on BP document, because I think we even disagree on that, not even about the number of documents.

Do we want 1 document, 2 documents or 3 documents?

Once we agree, depending on the outcome, can we then only discuss the contents of the one Basic Profile document and content ordering only up "Publish & Subscribe" and "Remote Procedure Calls"?

What content do we want a newcomer to read, in which order?

---

E.g. for me, it doesn't make sense to talk about "Protocol Overview" before "Building Blocks".

And in fact, before talking about these things, IMO the most important guiding aspects should be introduced first:

• design paradigms
• security model

as well as a "common language" defined

• terminology

and only after that

• protocol building blocks
• protocol overview

described.

At this point, PubSub + RPC are the big two chunks to be discussed which make up WAMP, and each should be introduced in three sections corresponding to the respective three main actions in each of PubSub and RPC.

Anyways, just my opinion. However, as long as we don't agree I think it is a waste of time to work it into PRs.

[meejah]

I would put most effort into the "Abstract" (this is where you get people excited enough to read more ... or lose them) and then "Introduction" (where you get a few more minutes / paragraphs to further hook anyone who didn't already leave).

After that, it's about well-organized and easy-to-find information for anyone who is already interested or "in" to WAMP etc.

A quick search didn't turn up where the words "1. Abstract" in the above screen-shots came from, but I can try editing etc if interested.

[oberstet]

I would put most effort into the "Abstract" (this is where you get people excited enough to read more ... or lose them)

I really like this kinda thinking! winning the reader's attention in the first place should be upfront, laying out the "core" of it ("WAMP in a nutshell"), convincing rgd the "why" it matters (what's the point anyways), and ultimately why the reader should continue and how the reader can get involved!

once at that point, as you say, the rest of it should be clear and easy to dig through/into any desired / required amount of details

one more note: "security" for me is part of the "absolute essential" - including clearly stated security goals / model (which currently is quite at the end of BP https://wamp-proto.org/wamp_latest_ietf.html#name-security-model) - as is "decoupling" (where WAMP comes from) ...

[meejah]

Yes, I would certainly highlight the security aspects in "abstract", including "end-2-end message encryption". Despite renewed emphasis on "security" this is still a pretty unique feature for any routed protocol, let along a real-time one like WAMP.

[oberstet]

highlight the security aspects in "abstract", including "end-2-end message encryption".

yes, agreed! unfort., only portions of it currently have text in AP spec

https://wamp-proto.org/wamp_ap_latest_ietf.html#name-advanced-security-features

I started and have half-done/ready text .. but ...

and the feature (e2e payload encr.) while having a working impl. in Crossbar.io/Autobahn lacks any other impls (as far as I know) currently. it has impls. in multiple AutobahnXXs ..

on the other hand CB/AB impls also have prototype impls. of the final stage of WAMP .. which isn't e2e in itself, but decentralized management of the trust relations established between e2e encrypting WAMP clients/app endpoints (the apps that do PubSub and RPC and which want the payload in those events/calls to be protected even from the routing infra ..)

[KSDaemon]

I think there is somewhere e2ee description that I was working on (IIRC in your fork @oberstet ). Maybe we can push it to this repo and continue working...

I hope I'll get some stamina to implement e2ee in some of the wamp implementations under my wing...

[oberstet]

I think there is somewhere e2ee description that I was working on (IIRC in your fork @oberstet ). Maybe we can push it to this repo and continue working...

I hope I'll get some stamina to implement e2ee in some of the wamp implementations under my wing...

that would be fantastic! both of it! collaborating on

• polishing/nailing the E2E spec proposal text, and
• your implementation in one of your WAMP implementations and testing interoperability with AB/CB

and "testing interoperability" / "one of your implementations" .. any of or even all of the following would be perfect!

[1]

• your WAMP client implementation, testing vs CB router implementation of E2E, and
• your router WAMP implementation, testing vs AB client implementation of E2E, and

[2]

• testing CB router implementation with your router implementation, for E2E over rlinks ! that is, WAMP E2E client traffic routed between router nodes of different implementations

and finally (this is yet another piece, but the real final one), if we then both would operate those different router implementations, running router nodes (and clients) of both implementations "cross-fashion" would allow pretty good verification of real interop and of course "does the spec make sense"! so what I mean:

[3]

• because that (different operators, not only different implementations) would need to test the decentralized management as well! as "you" and "me" == 2 indepedent router nodes (and clients) operators (not "only" implementors of a respective WAMP router/client) => that would be the ultimate / final interop test=)

The end goal of WAMP. Nirvana;) Or something. But I would say, preeeetty coool!

fwiw, should you decide to do it, I would be highly interested in collaborating! even for only [1], or even better [1+2], and of course best [1+2+3] !! but any start is a start, so I'd be ready to collaborate/work on it. obviously this would be an effort and PRs independent of this one.

[oberstet]

one more comment, in general, "working on spec" and "testing interop", with different implementations and operators is in my eyes really the only way of hashing it out, nailing the spec, shaking out bugs, and all of it.

without demonstrating different (independent) implementations and different operators working together, it's just words on paper.

with that, words will be scrutinized and polished by necessity and proven by demonstration!

rough consensus and working code=)

[SunFulong]

@oberstet Let's discuss this version:

No content text modify;
Moved some sections from BP to BASE;
Downgrade 1 level for all profile sections.

And I tried move BP vs AP to frontmatter, but it seems current xml2rfc does not support.

[SunFulong]

ping @oberstet @KSDaemon ...

[oberstet]

I don't support changing and moving around sections unless/until we do have reached sufficient consensus

my own proposal is here: #519 (comment)

I lost sight of other's proposals, consolidated ones.

IOW: how do we discuss restructuring proposals so they are easy to track and compare?

right now, it's a big mess .. in my eyes ... at least I don't have a clue what is actually proposed (on the table) .. I don't have time to wade through pages and pages of changes in a PR which is sprinkled with various other changes as well

I would suggest to cut proposed changes into smaller and logically coherent PRs.

eg 1 PR with all structural changes, but only those, and only after we agreed on the structure.

I don't know how to best discuss TOC changes (the structure&titles) .. some kind of table like .. but how to allow multiple people to submit their proposed changes, and still have only 1 big table with alternatives which are easy to compare ... mmmh .. any ideas?

[SunFulong]

Sure, I don't mind reopen much PRs with small change, and we can using one TOC only issue or discuss to trace structure change

[oberstet]

thank you!

reopen much PRs with small change

yes, smaller PRs and self-contained PRs, as in "one topic / thing" at a time would be highly welcome!

of course creating those will be more work on your side.

BUT:

you want to get those changes merged.

and for that, we need consensus, and that is much easier with smaller self-contained change packets (PRs)

if you think like: "minimize the collective work required", then I'd say "one big PR" is clearly at disadvantage compare to "many smaller self-contained" ones

changing the overall TOC / structure has yet an additional challenge: it is not just substance matter, but the ordering depends a lot on "perspective & taste", and everyone has a fav opinion ;)

plus the challenge of how to easily discuss structural/TOC changes