feat: add api/health, json responses with info about each message thrown

2026-06-04 11:05:41 -04:00 · 2025-04-08 15:30:33 -07:00
parent c017578631
commit 279d48d8ee
2 changed files with 179 additions and 26 deletions
--- a/README.md
+++ b/README.md
@@ -69,6 +69,7 @@
  - [Docker Compose](#docker-compose-1)
  - [Environment Variables](#environment-variables-1)
  - [Mountable Volumes](#mountable-volumes-1)
+  - [Docker health check](#docker-health-check)
 - [Traefik Integration](#traefik-integration)
  - [Labels](#labels)
  - [Dynamic.yml](#dynamicyml)
@@ -84,6 +85,7 @@
    - [Run Error: `Error serving playlist: ENOENT: no such file or directory, open /usr/src/app/xmltv.1.xml`](#run-error-error-serving-playlist-enoent-no-such-file-or-directory-open-usrsrcappxmltv1xml)
    - [Build Error: `s6-rc-compile: fatal: invalid /etc/s6-overlay/s6-rc.d/certsync/type: must be oneshot, longrun, or bundle`](#build-error-s6-rc-compile-fatal-invalid-etcs6-overlays6-rcdcertsynctype-must-be-oneshot-longrun-or-bundle)
    - [Build Error: `unable to exec /etc/s6-overlay/s6-rc.d/init-envfile/run: Permission denied`](#build-error-unable-to-exec-etcs6-overlays6-rcdinit-envfilerun-permission-denied)
+    - [Build Error: `[ERR] [27] Jellyfin.LiveTv.Guide.GuideManager: Error getting programs for channel XXXXXXXXXXXXXXX (Source 2) System.Xml.XmlException: '', hexadecimal value 0x1F, is an invalid character. Line 1, position 1.`](#build-error-err-27-jellyfinlivetvguideguidemanager-error-getting-programs-for-channel-xxxxxxxxxxxxxxx-source-2-systemxmlxmlexception--hexadecimal-value-0x1f-is-an-invalid-character-line-1-position-1)
 - [Extra Notes](#extra-notes)
  - [Accessing Container Shell](#accessing-container-shell)
    - [ash](#ash)
@@ -153,11 +155,12 @@ For the [environment variables](#environment-variables), you may specify these i
 | `TZ` | `Etc/UTC` | Timezone for error / log reporting |
 | `WEB_IP` | `0.0.0.0` | IP to use for webserver |
 | `WEB_PORT` | `4124` | Port to use for webserver |
+| `WEB_ENCODING` | `deflate, br` | Defines the HTTP `Accept-Encoding` request and response header. This value specifies what content encoding the sender can understand<br /><br />Gzip compression can be enabled by specifying `'gzip, deflate, br'` |
 | `URL_REPO` | `https://git.binaryninja.net/BinaryNinja/` | Determines where the data files will be downloaded from. Do not change this or you will be unable to get M3U and EPG data. |
 | `FILE_URL` | `urls.txt` | Filename for url cache file |
 | `FILE_M3U` | `playlist.m3u8` | Filename for M3U playlist file |
 | `FILE_EPG` | `xmltv.xml` | Filename for XML guide data file |
-| `FILE_GZIP` | `xmltv.xml.gz` | Filename for XML compressed as gzip .gz |
+| `FILE_GZP` | `xmltv.xml.gz` | Filename for XML compressed as gzip .gz |
 | `STREAM_QUALITY` | `hd` | Stream quality<br />Can be either `hd` or `sd` |
 | `DIR_BUILD` | `/usr/src/app` | Path inside container where TVApp2 will be built. <br /><br /> <sup>⚠️ This should not be used unless you know what you're doing</sup> |
 | `DIR_RUN` | `/usr/bin/app` | Path inside container where TVApp2 will be placed after it is built <br /><br /> <sup>⚠️ This should not be used unless you know what you're doing</sup> |
@@ -1189,11 +1192,12 @@ This docker container contains the following env variables:
 | `TZ` | `Etc/UTC` | Timezone for error / log reporting |
 | `WEB_IP` | `0.0.0.0` | IP to use for webserver |
 | `WEB_PORT` | `4124` | Port to use for webserver |
+| `WEB_ENCODING` | `deflate, br` | Defines the HTTP `Accept-Encoding` request and response header. This value specifies what content encoding the sender can understand<br /><br />Gzip compression can be enabled by specifying `'gzip, deflate, br'` |
 | `URL_REPO` | `https://git.binaryninja.net/BinaryNinja/` | Determines where the data files will be downloaded from. Do not change this or you will be unable to get M3U and EPG data. |
 | `FILE_URL` | `urls.txt` | Filename for `urls.txt` cache file |
 | `FILE_M3U` | `playlist.m3u8` | Filename for M3U playlist file |
 | `FILE_EPG` | `xmltv.xml` | Filename for XML guide data file |
-| `FILE_GZIP` | `xmltv.xml.gz` | Filename for XML compressed as gzip .gz |
+| `FILE_GZP` | `xmltv.xml.gz` | Filename for XML compressed as gzip .gz |
 | `STREAM_QUALITY` | `hd` | Stream quality<br />Can be either `hd` or `sd` |
 | `DIR_BUILD` | `/usr/src/app` | Path inside container where TVApp2 will be built. <br /><br /> <sup>⚠️ This should not be used unless you know what you're doing</sup> |
 | `DIR_RUN` | `/usr/bin/app` | Path inside container where TVApp2 will be placed after it is built <br /><br /> <sup>⚠️ This should not be used unless you know what you're doing</sup> |
@@ -1211,6 +1215,51 @@ These paths can be mounted and shared between the TVApp2 docker container and yo
 | `📁 /usr/bin/app` | <sub>Path where TVApp2 files will be placed once the app has been built. Includes `📄 formatted.dat`, `📄 xmltv.1.xml`, `📄 urls.txt`, `📁 node_modules`, and `📄 package.json`</sub> |
 | `📁 /config` | <sub>Where logs will be placed, as well as the web server generated SSH key and cert `🔑 cert.key` and `🪪 cert.crt`</sub> |

+<br />
+<br />
+
+### Docker health check
+
+This image includes a docker health check that you can define in your `📄 docker-compose.yml` file. You can view the health check status by opening your browser and going to your TVApp2 container's `health` path:
+
+```
+http://container-ip:4124/api/health
+```
+
+<br />
+
+You should see something similar to the following response:
+
+```json
+{
+  "ip": "172.XX.XX.4",
+  "gateway": "172.XX.XX.1",
+  "uptime": 2703.316357306,
+  "message": "Healthy",
+  "timestamp": 1744152471451
+}
+```
+
+<br />
+
+To apply a health check, open your TVApp2 `docker-compose.yml` and add any of the following options:
+
+```yml
+# Example 1 (Using curl)
+health check:
+    test: "curl --fail --silent http://127.0.0.1:${JELLYFIN_SCRAPER_TVAPP2_PORT_MAIN:-4124}/api/health | grep -i healthy || exit 1"
+    interval: 15s
+    timeout: 10s
+    retries: 3
+
+# Example 1 (Using wget)
+health check:
+    test: "wget -qO- http://127.0.0.1:${JELLYFIN_SCRAPER_TVAPP2_PORT_MAIN:-4124}/api/health | grep -i healthy || exit 1"
+    interval: 15s
+    timeout: 10s
+    retries: 3
+```
+
 <br />

 ---
@@ -1844,6 +1893,39 @@ find ./ -name 'run' -exec sudo chmod +x {} \;

 After you have set these permissions, re-build your docker image using `docker build` or `docker buildx`. Then spin the container up.

+<br />
+<br />
+
+#### Build Error: `[ERR] [27] Jellyfin.LiveTv.Guide.GuideManager: Error getting programs for channel XXXXXXXXXXXXXXX (Source 2) System.Xml.XmlException: '', hexadecimal value 0x1F, is an invalid character. Line 1, position 1.`
+
+This error may be seen if you are attempting to import our EPG guide data directly into Jellyfin. The cause of this is due to you having **GZIP Compression** enabled in your header request and response. See the example below; which is in your TVApp2 `📄 docker-compose.yml` file:
+
+```yml
+    tvapp2:
+        container_name: tvapp2
+        image: ghcr.io/thebinaryninja/tvapp2:latest
+        hostname: tvapp2
+        restart: unless-stopped
+        environment:
+            LOG_LEVEL: 10
+            WEB_ENCODING: 'gzip, deflate, br'
+```
+
+<br />
+
+To fix the issue, add or change the environment variable `WEB_ENCODING` and ensure `gzip` is not specified in the list like the following:
+
+```yml
+    tvapp2:
+        container_name: tvapp2
+        image: ghcr.io/thebinaryninja/tvapp2:latest
+        hostname: tvapp2
+        restart: unless-stopped
+        environment:
+            LOG_LEVEL: 10
+            WEB_ENCODING: 'deflate, br'
+```
+
 <br />

 ---
--- a/tvapp2/index.js
+++ b/tvapp2/index.js
@@ -110,7 +110,7 @@ const subdomainM3U = [ 'playlist', 'm3u', 'm3u8' ];
 const subdomainEPG = [ 'guide', 'epg', 'xml' ];
 const subdomainKey = [ 'key', 'keys' ];
 const subdomainChan = [ 'channels', 'channel' ];
-const subdomainHealth = [ 'status', 'health' ];
+const subdomainHealth = [ 'api/status', 'api/health' ];

 /*
    Container Information
@@ -118,10 +118,10 @@ const subdomainHealth = [ 'status', 'health' ];
    these environment variables are defined from the s6-overlay layer of the docker image
 */

-const fileIpGateway = '/var/run/s6/container_environment/IP_GATEWAY'
-const fileIpContainer = '/var/run/s6/container_environment/IP_CONTAINER'
-const envIpGateway = fs.existsSync(fileIpGateway) ? fs.readFileSync(fileIpGateway, 'utf8') : `0.0.0.0`;
-const envIpContainer = fs.existsSync(fileIpContainer) ? fs.readFileSync(fileIpContainer, 'utf8') : `0.0.0.0`;
+const fileIpGateway = '/var/run/s6/container_environment/IP_GATEWAY';
+const fileIpContainer = '/var/run/s6/container_environment/IP_CONTAINER';
+const envIpGateway = fs.existsSync( fileIpGateway ) ? fs.readFileSync( fileIpGateway, 'utf8' ) : `0.0.0.0`;
+const envIpContainer = fs.existsSync( fileIpContainer ) ? fs.readFileSync( fileIpContainer, 'utf8' ) : `0.0.0.0`;

 /*
    Define > Logs
@@ -574,13 +574,23 @@ async function serveKey( req, res )
        const uriParam = new URL( req.url, `http://${ req.headers.host }` ).searchParams.get( 'uri' );
        if ( !uriParam )
        {
-            res.writeHead( 400, {
-                'Content-Type': 'text/plain'
-            });
-
            Log.error( `Missing "uri" parameter for key download`, chalk.white( `→` ), chalk.grey( `${ req.url }` ) );

-            return res.end( 'Error: Missing "uri" parameter for key download.' );
+            const statusCheck =
+            {
+                ip: envIpContainer,
+                gateway: envIpGateway,
+                uptime: process.uptime(),
+                message: 'Error: Missing "uri" parameter for key download.',
+                code: 400,
+                timestamp: Date.now()
+            };
+
+            res.writeHead( 400, {
+                'Content-Type': 'application/json'
+            });
+
+            return res.end( JSON.stringify( statusCheck ) );
        }

        const keyData = await fetchRemote( uriParam );
@@ -594,11 +604,21 @@ async function serveKey( req, res )
    {
        Log.error( `ServeKey Error:`, chalk.white( `→` ), chalk.grey( `${ err.message }` ) );

+        const statusCheck =
+        {
+            ip: envIpContainer,
+            gateway: envIpGateway,
+            uptime: process.uptime(),
+            message: 'Error fetching key',
+            code: 500,
+            timestamp: Date.now()
+        };
+
        res.writeHead( 500, {
-            'Content-Type': 'text/plain'
+            'Content-Type': 'application/json'
        });

-        res.end( 'Error fetching key.' );
+        res.end( JSON.stringify( statusCheck ) );
    }
 }

@@ -741,13 +761,26 @@ async function serveM3UPlaylist( req, res )
        if ( !urlParam )
        {
            Log.error( `Missing parameter`, chalk.white( `→` ), chalk.grey( `URL` ) );
+
+            const statusCheck =
+            {
+                ip: envIpContainer,
+                gateway: envIpGateway,
+                uptime: process.uptime(),
+                message: 'Missing URL parameter',
+                code: 404,
+                timestamp: Date.now()
+            };
+
            res.writeHead( 400, {
-                'Content-Type': 'text/plain'
+                'Content-Type': 'application/json'
            });
-            res.end( 'Error: Missing URL parameter.' );
+
+            res.end( JSON.stringify( statusCheck ) );
            return;
        }

+
        const decodedUrl = decodeURIComponent( urlParam );
        if ( decodedUrl.endsWith( '.ts' ) )
        {
@@ -779,11 +812,22 @@ async function serveM3UPlaylist( req, res )
        {
            Log.error( `Failed to retrieve tokenized URL` );

+            const statusCheck =
+            {
+                ip: envIpContainer,
+                gateway: envIpGateway,
+                uptime: process.uptime(),
+                message: 'Error: Failed to retrieve tokenized URL.',
+                code: 500,
+                timestamp: Date.now()
+            };
+
            res.writeHead( 500, {
-                'Content-Type': 'text/plain'
+                'Content-Type': 'application/json'
            });

-            res.end( 'Error: Failed to retrieve tokenized URL.' );
+            res.end( JSON.stringify( statusCheck ) );
+
            return;
        }

@@ -804,11 +848,21 @@ async function serveM3UPlaylist( req, res )

        if ( !res.headersSent )
        {
+            const statusCheck =
+            {
+                ip: envIpContainer,
+                gateway: envIpGateway,
+                uptime: process.uptime(),
+                message: 'Error: Cannot process request.',
+                code: 500,
+                timestamp: Date.now()
+            };
+
            res.writeHead( 500, {
-                'Content-Type': 'text/plain'
+                'Content-Type': 'application/json'
            });

-            res.end( 'Error processing request.' );
+            res.end( JSON.stringify( statusCheck ) );
        }
    }
    finally
@@ -834,6 +888,7 @@ async function serveHealthCheck( req, res )
            gateway: envIpGateway,
            uptime: process.uptime(),
            message: 'Healthy',
+            code: 200,
            timestamp: Date.now()
        };

@@ -841,7 +896,7 @@ async function serveHealthCheck( req, res )
            'Content-Type': 'application/json'
        });

-        res.end( JSON.stringify(healthcheck) );
+        res.end( JSON.stringify( healthcheck ) );
        return;
    }
    catch ( err )
@@ -856,7 +911,7 @@ async function serveHealthCheck( req, res )
                gateway: envIpGateway,
                uptime: process.uptime(),
                message: 'Unhealthy',
-                status: 0,
+                code: 503,
                timestamp: Date.now()
            };

@@ -864,7 +919,7 @@ async function serveHealthCheck( req, res )
                'Content-Type': 'application/json'
            });

-            res.end( JSON.stringify(healthcheck) );
+            res.end( JSON.stringify( healthcheck ) );
        }
    }
    finally
@@ -1265,9 +1320,25 @@ const server = http.createServer( ( request, response ) =>
                    Log.notice( `www`, chalk.yellowBright( ` [NOTICE] ` ), chalk.white( `→` ), chalk.grey( `If you are attempting to load TVApp2 using an HDHomeRun tuner, please switch to the` ), chalk.yellowBright( `M3U Tuner` ) );
                }

-                Log.error( `www`, chalk.redBright( ` [ERROR] ` ), chalk.white( `→` ), chalk.grey( `File not found:` ), chalk.redBright( `${ request.url }` ) );
-                response.writeHead( 404, 'Not Found' );
-                response.end();
+                Log.error( `www`, chalk.redBright( ` [ERROR] ` ), chalk.white( `→` ), chalk.grey( `File not found:` ), chalk.redBright( `${ loadFile }` ) );
+
+                const statusCheck =
+                {
+                    ip: envIpContainer,
+                    gateway: envIpGateway,
+                    uptime: process.uptime(),
+                    message: 'Page not found',
+                    ref: request.url,
+                    method: method,
+                    code: 404,
+                    timestamp: Date.now()
+                };
+
+                response.writeHead( 404, {
+                    'Content-Type': 'application/json'
+                });
+
+                response.end( JSON.stringify( statusCheck ) );
            }
        });
    };