Server Side Events (SSE)

overview server sent events (sse) is a server push technology that enables a client to receive automatic updates from a server over an http connection once the initial client connection is established, the server can continuously push real time data to the client without requiring repeated requests os1 makes sse easy to implement, enabling developers to set up real time data streaming with minimal effort it reduces management overhead while ensuring reliable and scalable event driven communication the server side events (sse) feature enables app developers to build more responsive web applications with the ability to receive real time response data directly from the console ui this is achieved through a server sent event communication, enabling a seamless and immediate data flow from the console to the web app upon initiating an api request the native push based data delivery not only enables faster, real time frontend experiences but also streamlines infrastructure efficiency 📘 note note this feature is only available for web apps that integrate with console prerequisites to implement sse, you need to instantiate the os1httpclient from the console ui the os1httpclient is a wrapper http client provided by the console ui to make it easier to support post , put , patch , delete http methods necessary for restful api calls it is a pre configured instance of axios https //axios http com/docs/intro that handles authentication, base urls, and other http client best practices // import from console ui context import { os1httpclient } from 'console/http'; // instantiate const httpclient = new os1httpclient( consolecontext authinitializer, process env base url ); the os1httpclient takes two arguments the first is props console authinitializer , which contains the authentication context or initialization parameters necessary for the client to make authenticated requests the second argument is the process env base url is for the api endpoints that the application will communicate with the sse client id has a lifespan of 1 hour if this limit is exceeded, the api will throw an error to establish a connection again, you need to refresh the page implementation this guide details the integration of server side events (sse) using the os1httpclient class provided by the console, allowing for real time communication from server to client in your application there are two ways to implement server side events (sse) in your application option 1 using the {{sse callback}} placeholder this is the simplest option if using the console’s axios client step 1 setting the callback url parameter when making an api call, specify the attribute where the callback url is expected on the backend and its value needs to be set by using the placeholder {{sse callback}} the console will automatically detect and replace this placeholder with the actual callback url developers can pass the callback attribute in the request url, headers, or the request body the example below adds {{sse callback}} to the header for the createvehicles request try { await axiosclient post( '/vehicles', dto, // the payload for the api call 'createvehicles', // the operation or function being called { withauth false }, // options, set to false if authentication is not required { headers { 'callback' "{{sse callback}}", // updated automatically by the axios client 'content type' 'application/json', // set the content type of the request } } ); } catch (error) { console error('error', error); } internally, the os1httpclient will manage the sse connection and retrieve the callback url from the server if the {{sse callback}} placeholder is present and will replace the variable where the callback url is needed in the api request step 2 listen to sse events once a callback is received from the server, the console will emit a custom event, ssecallbackevent your application needs to listen to this event in your ui code and handle the data when the api response is pushed from the server document addeventlistener(`${consoleinstance events() ssecallbackevent}`, (eventdata) => { // handle the event data }); const dto = { callback { url "{{sse callback}}", meta {}, }, }; try { await axiosclient delete( `/vehicles/${vehicleid}`, dto, // the payload for the api call "deletevehicles", // the operation or function being called {withauth false}, // options, set to false if authentication is not required { headers { callback "{{sse callback}}", // updated automatically by the axios client "content type" "application/json", // set the content type of the request }, } ); } catch (error) { console error("error", error); } delete request with {{sse callback}} the os1httpclient can handle delete requests with sse users can pass {{sse callback}} in the headers, data payload, or query parameters, allowing the console to intercept the request and replace {{sse callback}} with the actual sse callback url the example below shows a delete request by passing {{sse callback}} in both the header and payload javascrip ```javascript const dto = { callback { url "{{sse callback}}", meta {}, }, }; try { await axiosclient delete( `/vehicles/${vehicleid}`, dto, // the payload for the api call "deletevehicles", // the operation or function being called {withauth false}, // options, set to false if authentication is not required { headers { callback "{{sse callback}}", // updated automatically by the axios client "content type" "application/json", // set the content type of the request }, } ); } catch (error) { console error("error", error); } ``` error handling if there are any internal errors during connection setup, the console will throw an error, and an api call will be made with null as the callback url only non retriable errors will be thrown to the user example implementation the following sample code demonstrates the full implementation for using the {{sse callback}} placeholder // import and instantiate http client import { os1httpclient } from 'console/http'; const httpclient = new os1httpclient(consolecontext authinitializer, base url); // make api request with placeholder const makerequest = async () => { try { const response = await httpclient post('/api', data, { headers { 'callback' '{{sse callback}}' } }); console log(response); } catch (error) { console error(error); } }; // listen for callback event document addeventlistener(consolecontext events ssecallbackevent, (event) => { const data = event data; // callback payload // handle data }); // initiate request makerequest(); the implementation does the following imports and instantiates the os1httpclient makes an api call with the {{sse callback}} placeholder console will swap the placeholder with the actual url listens for the ssecallbackevent callback the event data contains the response payload option 2 calling the geteventbrokerurl this option works with any http client and is not limited to console’s axios client step 1 call the geteventbrokerurl when you are ready to make an api call, ensure that the geteventbrokerurl function is invoked to verify or refresh the callback url this function will maintain the connection and provide the callback url for the api request see the example code below const callbackresponse = await cl geteventbrokerurl(); setcallbackurl(callbackresponse callback); // set the new callback url in state step 2 store the returned callback url store the returned callback url in a component state variable or global context object this allows referencing it when making api calls // store in component state const \[callbackurl, setcallbackurl] = usestate(null); const geturl = async () => { const url = await httpclient geteventbrokerurl(); setcallbackurl(url); } // store in global context context callbackurl = await httpclient geteventbrokerurl(); step 3 making api calls make your api request by passing the callback url as a parameter, header, or elsewhere in the request const makerequest = async () => { try { const response = await httpclient post('/api', data, { headers { 'callback' callbackurl } }); // handle response } catch (error) { // handle error } } step 4 listen for ssecallbackevent once a callback is received from the server, the console will emit a custom event, ssecallbackevent your application can listen to this event in your ui code and handle the data when the api response is pushed from the server document addeventlistener(`${consoleinstance events() ssecallbackevent}`, (eventdata) => { // handle the event data }); optimize the callback url state developers can use the useeffect hook to optimize the state management and avoid unnecessary re fetching see the following code below // store callback url in state const \[callbackurl, setcallbackurl] = usestate(null); useeffect(() => { // fetch latest callback url const fetchurl = async () => { const url = await httpclient geteventbrokerurl(); setcallbackurl(url); }; fetchurl(); }, \[callbackurl]); // only update state if url changed const makerequest = async () => { const newurl = await httpclient geteventbrokerurl(); if (newurl !== callbackurl) { setcallbackurl(newurl); return; } // make api call using current callbackurl }; example implementation the following example shows how to implement sse into an application by manually calling the geteventbrokerurl // import and instantiate http client import { os1httpclient } from 'console/http'; const httpclient = new os1httpclient(consolecontext authinitializer, base url); // callback url state const \[callbackurl, setcallbackurl] = usestate(null); // get initial url const geturl = async () => { const url = await httpclient geteventbrokerurl(); setcallbackurl(url); } useeffect(() => { geturl(); }, \[]); // make request const makerequest = async () => { // get updated url const newurl = await httpclient geteventbrokerurl(); // only update state if changed if (newurl !== callbackurl) { setcallbackurl(newurl); return; } // make api call const response = await httpclient post('/api', data, { headers { 'callback' callbackurl } }); }; // listen for callback event document addeventlistener(consolecontext events ssecallbackevent, (event) => { // handle event }); // initiate request makerequest(); the implementation does the following imports and instantiates http client manages callback url state calls useeffect to fetch initial url calls the geteventbrokerurl before each request only updates the state if the url changed passes the callbackurl state in the request listens for ssecallbackevent