Add metadata extension for Route Advertising

[smaldini]

With #254 we can now forward routing information alongside any rsocket request.
Mediation layers (gateway, sidecar, proxy...) and discoverable services might still need to register explicit routes interests on remote client connection setup.

Advertising routes could be done with the same routing metadata mime type attached on connection payload and possibly updated dynamically with more metadata pushes. We can consider the latter in a different issue.

[yschimke]

+1 I'd love to be able to make the CLI tools complete routes for endpoints

[yschimke]

I guess, what is a discoverable OpenAPI for RSocket?

[whyoleg]

https://github.com/rsocket-routing/rsocket-routing has such functionality, isn't it?
Looks like it's better place for it

[yschimke]

@whyoleg do you have overlap to transfer this?

[OlegDokuka]

rsocket-routing/rsocket-routing has such functionality, isn't it?
Looks like it's better place for it

it has not.

I guess, what is a discoverable OpenAPI for RSocket?

Technically, it can be a good idea to add a spec extension for OpenAPI or develop something identical to that. This is a demandable feature and I was asked about Swagger compatibility a couple of times.

Does anybody want to start a PR?

[OlegDokuka]

@yschimke

Advertising routes could be done with the same routing metadata mime type attached on connection payload and possibly updated dynamically with more metadata pushes. We can consider the latter in a different issue.

Although I don't think a connection setup phase is a good place for transferring that since we don't have any handshake mechanism which allows both sides to transfer routes via setup payload metadata. The only possible option is metadata push as a way to push information about available routes.

E.g, if it is a swagger-like client connects to any server, it may do metadata_push([WellknownMimeType.AdvertiseRoutes : Buffer.EMPTY]) so the responder may receive it and then do another metadata_push([WellKnownMimeTypes.RoutesMapping : Buffer.from(encoded_routes))

[yschimke]

Seems wasteful to always send it. Perhaps a request at a known route. Also it's awkward to wait for it when you don't know for sure if it's coming. Maybe an implicit route on a requestResponse operation?

Something like https://en.wikipedia.org/wiki/List_of_/.well-known/_services_offered_by_webservers

.well-known/routes ->

{
"routes": [
{
 {"route": "searchTweets"},
 {"route": "timer"},
 {"route": "tweet/{id}"},
 {}
}
]
}

[OlegDokuka]

@yschimke

Maybe an implicit route on a requestResponse operation?

I guess if we request routes via requestResponse, it may end up with an error or unpredicted response, e.g. in the case when an application framework does not support routing advertisement but suddenly receive unwanted requestResponse.

Seems wasteful to always send it. Perhaps a request at a known route. Also it's awkward to wait for it when you don't know for sure if it's coming.

What if this is not an operation that should ever happen? Imagine a dynamic mechanic which may react to a received metadata_push that advertises remote party routes. Since this is metadata_push, the responder may ignore it which is fine. In case it is an expected request, the responder upon reception of that message may enable additional functionality.

For example, in the case of CLI tool, before reception of the metadata-push message, CLI may have route autocompletion disabled, but once metadata_push happens, it may enable it so all the following interactions will have autocompletion.

In the case of swagger-like UI, the browser client will be displaying zero routes, but once metadata_push will be received, the UI will react and render received info

[yschimke]

+1 worth speccing out.

I was curious if there was some nice intermediate step to get a ["searchTweets", "timer", "tweet/{id}"] from a server I connect to. metadata push is terrible for this because you don't know when to stop waiting.

[linghengqian]

• I don't quite understand why the above discussion involves Swagger, because Swagger is an ecosystem for OpenAPI, but OpenAPI does not accept specifications like WebSocket (refer to Websocket spec proposal OAI/OpenAPI-Specification#2881 ) . The event-driven model like WebSocket should actually move to AsyncAPI, and the documentation written by AsyncAPI Studio is similar to Swagger UI.

[olme04]

Now, after some time working on rsocket, I have an idea, that something like this can be implemented via an extension for a protocol using EXT frame, which at current moment are not implemented anywhere and there is no info about examples in spec.

EXT frame content provides us only type of extension, some payload and can it be ignored or not.

For route advertising, possible prototype extension workflow:

• send extension payload from requester to responder, which says, that we want to get supported routes
• responder, depending on if it's supported or not, will send extension payload back with supported routes

The only issue is that if we want to be able to make it both:

• safe to use with responders, that don't support such extension
• have possibility to know, if the response will come

We need to have some additional flag for EXT frame - now we have only (I)gnore flag, but looks like we will also want a flag, saying that if it's not supported, tell me about it, let's call it (A)cknowledgment flag. And we need counterpart frame (let's call it EXT_ACK) from responder to say, that extension is not supported, but don't close connection.

So, if responder supports EXT, it will do the logic, but if it don't support, then we will have following cases when requester sends EXT frame:

• if (I)gnore flag is SET and (A)cknowledgment flag is NOT SET - responder just ignores frame
• if (I)gnore flag is SET and (A)cknowledgment flag is SET - responder sends EXT_ACK with some data, that this extension is not supported
• if (I)gnore flag is NOT SET and (A)cknowledgment flag has any value - responder fails connection with ERROR frame

[linghengqian]

Is it possible to provide AsyncAPI with the necessary information for bindings RSocket without the issue being closed? A related issue has been put on hold, refer to asyncapi/bindings#18 .