Implement shared buffer for multiple clients per stream ID

[sonroyaalmerol]

Context

• This was previously attempted before the major code refactoring. Should close Follow ffmpeg's buffer behavior to reduce playback issues on slow connections #164
• This will be merged after Major refactoring for easier tests #218. Of course, after this draft is done.
• Instead of having different buffers per client, buffer will now be shared amongst clients per stream ID (the ID in the stream's URL). This only applies to non-m3u8 streams for now.
• This should result to "unlimited" client connections available for clients watching the same channel.

Choices

• Removed BUFFER_MB in favor of BUFFER_CHUNK_NUM which now refers to the number of chunks stored in the shared buffer with the defaults set to 4. Each chunk will be fixed to 1 MB.

How it works

The stream buffer system is essentially an implementation of a Circular Buffer data structure.

Imagine a circular sushi conveyor belt (ring.Ring) with a fixed number of plates (BUFFER_CHUNK_NUM). Each plate (ChunkData) can hold a piece of sushi (chunk of data).

The Chef (Writer)

At the preparation station, there's a chef (StartWriter) who:

• Takes raw fish (stream data) and cuts it into bite-sized pieces (ChunkSize)
• Places each piece on an empty plate (ChunkData)
• Puts the plate on the conveyor belt and moves to the next empty plate
• If something goes wrong with the fish (error), marks the plate with a warning flag

The chef works continuously unless:

• The restaurant closes (context cancelled)
• There are no more customers (client count drops to 0)
• They run out of fish (EOF)
• Something goes wrong in the kitchen (error)

The Customers (Readers)

Customers (ReadChunks) sitting at different points around the belt:

• Remember which plate they last looked at (fromPosition)
• Can look at all plates that have passed by since they last checked
• Make their own copy of each piece of sushi they want (copying the data)
• If they catch up to where the chef is currently placing plates, they wait (dataNotify.Wait())
• If they see a plate with a warning flag (error), they know to stop eating

If a customer is too slow and takes too long to check a plate, the data might get replaced by the time they look again (buffer overwrite)

This system ensures that streaming data (sushi) flows smoothly from the source (kitchen) to multiple consumers (customers) while efficiently managing memory (plates) and handling errors (food safety warnings).

Checklist before requesting a review

• I have performed a self-review of my code
• I've added documentation about this change to the README.
• I've not introduced breaking changes.

[sonroyaalmerol]

@kpirnie Sorry to bother you but do you mind trying this out? This is a completely different implementation of the existing (and dead simple) buffer but allows multiple clients to share one stream connection. I was wondering if this idea scales fine with the amount of providers you have.

Theoretically, the memory usage of this implementation should be proportional by the number of active connections to the IPTV providers and not the number of client connections necessarily.

[github-actions]

The Docker image for this pull request has been built and pushed to GHCR.

Image URL: ghcr.io/sonroyaalmerol/m3u-stream-merger-proxy:pr-220

[aniel300]

am having major buffering with this pr. idk if it something related to my set up or what

[sonroyaalmerol]

Hi @aniel300. I can't help you without any debug logs. Please create a new issue with more context. Also, there are important notes in the release changelog.