Request: more documentation (having trouble grokking)

[lefnire]

Sorry for the newbishness, I'm having trouble understanding how to use the project. Main points I struggle with:

• Coming from FastAPI/WebSockets, the docs have Depends(...) injected to routes. They use fastapi.app.websocket rather than starlette.routing.WebSocketRoute. Wondering what the simple translation from Starlette->FastAPI is to allow Depends() in the functions?
• If it's as simple as replacing WebSocketRoute("/", ...) with app.websocket("/"), where do I put my dependencies? Is it at the async def chatroom_ws(websocket, <add deps here>) level?
• Where/how do I handle on_connect, on_disconnect?
• What's going on with run_until_first_complete? I can't find documentation in Starlette, and when I dive into asyncio.wait(..., FIRST_COMPLETED) it seems to imply the first task to complete is solid, and what's left is cancelled? Which confuses me on the setup of receiver/sender, don't we want both?
• Looking at all the above, fastapi-websocket-broadcast has a pretty solid kitchen-sink example of subclassing WebSocketEndpoint with on_connect|disconnect|message, keeping websockets around for later use, etc. Maybe a more robust broadcaster sample in /examples could be in order for us FastAPI newbies?

[rafalp]

Hello!

None of questions you've asked apply to the Broadcaster itself ;)

Broadcaster is small library that provides unified API over the top of few technologies that support publish-subscribe model. This library only does three things:

• creates instance of pub-sub server via Broadcast(connection_string)
• enables applications to push messages to the server with broadcast.publish(...)
• enables applications to subscribe to the server to receive messages with broadcast.subscribe()

Everything else has to be implemented by the developer and is outside of this library's scope. If you take example's code and remove lines of code non-specific to the broadcaster, you will get this:

# Creates pub-sub service using Redis
broadcast = Broadcast("redis://localhost:6379")

# Sends "message" to the "chatroom" channel
await broadcast.publish(channel="chatroom", message=message)

# Receives messages sent to the "chatroom" channel and does something with them
  async with broadcast.subscribe(channel="chatroom") as subscriber:
      async for message in subscriber:
          do_something_with_message(message)

I'm sorry I'm unable to provide the example for FastAPI at this time, but hopefully this will make it little more clear what this library is and what it's not. :)

[lefnire]

Right, right - definitely not directly related, so it's mostly an out-of-scope question. And thanks for the quick response! Maybe I'll just follow-up here in case someone else has the same question, as the FastAPI Websockets docs points here, and it's not clear how to fit broadcaster's pub/sub into a WebsocketEndpoint class with on_receive.

I'll take a stab at using this on a project, then post a sample implementation here if I get it working.

[Buuntu]

I agree that even though it's not directly related, it would be super nice to have a very simple example of how to plug it into FastAPI, since there are only small differences between Starlette and FastAPI. @lefnire were you able to get it working? I'm also struggling with this.

[lefnire]

@Buuntu yep! See https://github.com/lefnire/gnothi/blob/groups/server/app/main.py and https://github.com/lefnire/gnothi/blob/groups/server/app/ws.py. My setup's pretty convoluted / sloppy, you may prefer https://github.com/authorizon/fastapi_websocket_pubsub, which uses Broadcaster under the hood - adding some sugar on top. See their examples at https://github.com/authorizon/fastapi_websocket_pubsub/tree/master/examples, and a related convo at https://github.com/authorizon/fastapi_websocket_pubsub/discussions/7

[lefnire]

All-in-all, this projects + the authorizon wrappers are really solid.

[Buuntu]

Thanks so much! Maybe you should post those on here too if you don't mind? fastapi/fastapi#3009

I'm a little frustrated by the lack of documentation because every Websocket thread on the FastAPI repo ends with "see https://github.com/encode/broadcaster", yet neither has a concrete example of how to use it with FastAPI. I do think that probably better belongs in the FastAPI docs, but it seems like a common enough use case that it should have documentation to me.