Bug: AsyncAPI generator produces unrenderable asyncapi.json if subscriber contains filter.

[dmigis]

Describe the bug
Faststream 0.6.5/0.6.6 AsyncAPI generator produces unrenderable asyncapi.json if subscriber contains filter.
When I open AsyncAPI doc in browser, I get the following error:

Error: There are errors in your Asyncapi document
0 Referencing in this place is not allowed

Without such handler AsyncAPI documentaion renders without errors.

How to reproduce

import asyncio
from faststream.rabbit import RabbitBroker
from faststream.asgi import AsgiFastStream
from faststream.specification import AsyncAPI

from pydantic import BaseModel


broker = RabbitBroker("amqp://guest:guest@localhost:5672/",)
app = AsgiFastStream(
        broker,
        specification=AsyncAPI(),
        asyncapi_path="/docs/asyncapi",
    )

subscriber = broker.subscriber("test-queue")

class Input(BaseModel):
    name: str

class Inp(BaseModel):
    sname: str

@subscriber(
    filter=lambda msg: msg.content_type == "application/json",
)
async def handle(d: Inp):
    print(d.sname)

@subscriber
async def default_handler(msg: Input):
    print(msg.name)


async def main() -> None:
    await app.run()

if __name__ == "__main__":
    asyncio.run(main())

1. Run the code above
2. Open http://127.0.0.1:8000/docs/asyncapi in browser
3. Get the mentioned error

Expected behavior
I'm expecting to get correctly rendered AsyncAPI documentation in browser

Observed behavior
When I open AsyncAPI doc in browser, I get the following error:

Error: There are errors in your Asyncapi document
0 Referencing in this place is not allowed

Without such handler AsyncAPI documentaion renders without errors.

Screenshots

Environment
Running FastStream 0.6.6 with CPython 3.12.4 on Darwin

[Lancetnik]

The problem is that https://github.com/asyncapi/parser-js doesn't allow use [] ion $ref for messages

"messages": {
        "SubscribeMessage": {
          "$ref": "#/components/messages/test-queue:_:[Handle,DefaultHandler]:SubscribeMessage"
        }
      },

But pretty the same ref in other places works fine

"channel": {
        "$ref": "#/channels/test-queue:_:[Handle,DefaultHandler]"
      },

[vvlrff]

👀

[daemonkeeper]

The problem is much wider than that. I don't have any filters, but I too get plenty of render errors. There are four distinct problems, at least when it comes to NATS subjects and their routing. You use NATS subject strings to derive identifiers and address values. The problem may be applicable to other message busses, too but I haven't tested.

You already identified the first issue. FastStream constructs channel identifiers by concatenating the NATS subject and the handler class name with a colon: "NATS.SUBJECT:HandlerName". This string is then used as both the channel map key and the value of channel.address. ":" however is not in a valid character set AsyncAPI 3.0 requires for components/messages keys.

Every $ref pointing at one of these entries (e.g. in my case "$ref": "#/components/messages/SERVICE.CONTROL.ACTIVATE:HandleServiceActivate") is therefore referencing a key that fails schema validation. You might want to substitute non-word characters there, as they are not URI compliant, as $ref uses them as anchors.

As a secondary consequence, channel.address ends up containing the handler name, which has no meaning as a routing address. I'd argue it does not belong there anyway. I understand why you do, you need uniqueness when multiple handlers subscribe to the same subject, but the separator must not be :. You might use __ or something like that. I'd also urge to set channel.address then independently to just the NATS subject.

Second, NATS uses ">" as wildcard for subjects (or, alike "*"), and does thus appears in channel/component identifiers and hence $ref paths. But that's not a valid URI fragment either, and this makes $ref malformed. The the spec enforces that component identifiers match a word-character pattern. The subject must be sanitized before passing to AsyncAPI (e.g. replace > by _gt_ or so)

Third, basically the same issue, ">" also appears in the channel address. For channels whose NATS subject contains wildcards (">", or "*"), channel.address should either be set to null or expressed using a valid URI template placeholder, e.g. "SERVICE.CONTROL.{+wildcard}".

The fourth may be a "me-problem", but subscriber subjects can sometimes contain Python/config template expressions, e.g. I have something like "SERVICE.STATE.{config.service_name}.{config.service_instance}". They are used verbatim. Again you need URI sanitation here, because you use them in $ref paths. That Python syntax is fine in channel.address (they are valid URI template syntax there), but not in object keys used as component identifiers.

On another note: you create 3.0 schemas, but you bundle react JS and CSS components at version 2.6.4. You may want to update the bundle.

Hooking into Faststreams AsyncAPIRoute factory and running $ref keys through a sanitizer like

def sanitize_asyncapi_key(key: str) -> str:
    return (
        key.replace(">", "_gt_")
        .replace("*", "_any_")
        .replace(":", "__")
        .replace("{", "")
        .replace("}", "")
    )

and, finally using the correct React JSS/CSS with

        _asyncapi_js = "https://unpkg.com/@asyncapi/react-component@3.0.2/browser/standalone/index.js"
        _asyncapi_css = "https://unpkg.com/@asyncapi/react-component@3.0.2/styles/default.min.css"

        async_api = AsyncAPI(
...
        )

        app = AsgiFastStream(
            specification=async_api,
            asyncapi_path=AsyncAPIRoute(
                "my-url",
                asyncapi_js_url=_asyncapi_js,
                asyncapi_css_url=_asyncapi_css,
            ),

gives me working API docs, but obviously that's not a "proper" fix.