StreamItem Schema

The StreamItem schema represents a real-time update notification for document changes in Rusty Beam. It is used by the WebSocket plugin to broadcast changes to subscribed clients.

Schema Definition

Schema URL: https://rustybeam.net/schema/StreamItem

Properties

Property	Type	Cardinality	Description
method	https://rustybeam.net/schema/Text	1	The HTTP method that triggered the update (PUT, POST, or DELETE)
url	https://rustybeam.net/schema/URL	1	The URL of the document that was modified
selector	https://rustybeam.net/schema/Text	1	The CSS selector that was used to target the content
content	HTML	1	The content that was modified (for POST/PUT: the new content; for DELETE: the removed content)

Example

<div itemscope itemtype="https://rustybeam.net/schema/StreamItem">
    <span itemprop="method">POST</span>
    <span itemprop="url">/blog/article.html</span>
    <span itemprop="selector">ul#comments</span>
    <div itemprop="content">
        <li>New comment added to the list</li>
    </div>
</div>

Usage Context

WebSocket Broadcasting

StreamItem is primarily used by the WebSocket plugin to notify connected clients about document changes. When a document is modified using the selector-handler plugin, a StreamItem is broadcast to all clients subscribed to that document.

Method Values

PUT - Content was replaced at the selector
POST - Content was appended to the selector
DELETE - Content was removed from the selector

Content Property

The content property contains different content based on the method:

For PUT: The new content that replaced the selected element
For POST: The content that was appended (not the entire container)
For DELETE: The content that was removed (before deletion)

Client Processing

JavaScript example for processing StreamItem:

ws.onmessage = (event) => {
    const parser = new DOMParser();
    const doc = parser.parseFromString(event.data, 'text/html');
    
    // Check if it's a StreamItem
    const streamItem = doc.querySelector('[itemtype="https://rustybeam.net/schema/StreamItem"]');
    if (streamItem) {
        const method = streamItem.querySelector('[itemprop="method"]')?.textContent;
        const url = streamItem.querySelector('[itemprop="url"]')?.textContent;
        const selector = streamItem.querySelector('[itemprop="selector"]')?.textContent;
        const content = streamItem.querySelector('[itemprop="content"]')?.innerHTML;
        
        console.log(`${method} ${url} ${selector}`, content);
        
        // Apply changes to local DOM based on method
        const target = document.querySelector(selector);
        if (target && content) {
            switch(method) {
                case 'POST':
                    // Append the new content
                    target.insertAdjacentHTML('beforeend', content);
                    break;
                case 'PUT':
                    // Replace with new content
                    target.outerHTML = content;
                    break;
                case 'DELETE':
                    // Content shows what was deleted, remove matching element
                    target.remove();
                    break;
            }
        }
    }
};

URL Normalization

The WebSocket plugin normalizes URLs so that directory paths and their index files are treated as the same subscription:

/ and /index.html receive the same broadcasts
/admin/ and /admin/index.html receive the same broadcasts