🔀 Merge pull request #72 from Lissy93/FEATURE_Custom-status-check-hea…

…ders

[FEATURE] Custom status check headers and url
Fixes #35

docs/configuring.md

@@ -106,6 +106,8 @@ All fields are optional, unless otherwise stated.
 **`icon`** | `string` | _Optional_ | The icon for a given item. Can be a font-awesome icon, favicon, remote URL or local URL. See [`item.icon`](#sectionicon-and-sectionitemicon)
 **`target`** | `string` | _Optional_ | The opening method for when the item is clicked, either `newtab`, `sametab`, `modal` or `workspace`. Where `newtab` will open the link in a new tab, `sametab` will open it in the current tab, and `modal` will open a pop-up modal with the content displayed within that iframe. Note that for the iframe to load, you must have set the CORS headers to either allow `*` ot allow the domain that you are hosting Dashy on, for some websites and self-hosted services, this is already set.
 **`statusCheck`** | `boolean` | _Optional_ | When set to `true`, Dashy will ping the URL associated with the current service, and display its status as a dot next to the item. The value here will override `appConfig.statusCheck` so you can turn off or on checks for a given service. Defaults to `appConfig.statusCheck`, falls back to `false`
+**`statusCheckUrl`** | `string` | _Optional_ | If you've enabled `statusCheck`, and want to use a different URL to what is defined under the item, then specify it here
+**`statusCheckHeaders`** | `object` | _Optional_ | If you're endpoint requires any specific headers for the status checking, then define them here 
 **`color`** | `string` | _Optional_ | An optional color for the text and font-awesome icon to be displayed in. Note that this will override the current theme and so may not display well
 **`backgroundColor`** | `string` | _Optional_ | An optional background fill color for the that given item. Again, this will override the current theme and so might not display well against the background
 

docs/status-indicators.md

@@ -48,10 +48,29 @@ appConfig:
   statusCheckInterval: 20
 ```
 
+## Using a Different Endpoint
+By default, the status checker will use the URL of each application being checked. In some situations, you may want to use a different endpoint for status checking. Similarly, some services provide a dedicated path for uptime monitoring. 
+
+You can set the `statusCheckUrl` property on any given item in order to do this. The status checker will then ping that endpoint, instead of the apps main `url` property.
+
+## Setting Custom Headers
+If your service is responding with an error, despite being up and running, it is most likely because custom headers for authentication, authorization or encoding are required. You can define these headers under the `statusCheckHeaders` property for any service. It should be defined as an object format, with the name of header as the key, and header content as the value.
+For example, `statusCheckHeaders: { 'X-Custom-Header': 'foobar' }`
+
+## Troubleshooting Failing Status Checks
+If the status is always returning an error, despite the service being online, then it is most likely an issue with access control, and should be fixed with the correct headers. Hover over the failing status to see the error code and response, in order to know where to start with addressing it.
+If your service requires requests to include any authorization in the headers, then use the  `statusCheckHeaders` property, as described above.
+If you are still having issues, it may be because your target application is blocking requests from Dashy's IP. This is a [CORS error](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS), and can be fixed by setting the headers on your target app, to include:
+```
+Access-Control-Allow-Origin: https://location-of-dashy/
+Vary: Origin
+```
+For further troubleshooting, use an application like [Postman](https://postman.com) to diagnose the issue.
+
 ## How it Works
 
 When Dashy is loaded, items with `statusCheck` enabled will make a request, to `https://[your-host-name]/ping?url=[address-or-servce]`, which in turn will ping that running service, and respond with a status code. Response time is calculated from the difference between start and end time of the request. 
 
-An indicator will display next to each item, and will be yellow while waiting for the response to return, green if request was successful, red if it failed, and grey if it was unable to make the request all together.
+When the response completes, an indicator will display next to each item. The color denotes the status: Yellow while waiting for the response to return, green if request was successful, red if it failed, and grey if it was unable to make the request all together.
 
-All requests are made straight from your server, there is no intermediary. So providing you are hosting Dashy yourself, and are checking the status of other self-hosted services, there shouldn't be any privacy concerns.
+All requests are made straight from your server, there is no intermediary. So providing you are hosting Dashy yourself, and are checking the status of other self-hosted services, there shouldn't be any privacy concerns. Requests are made asynchronously, so this won't have any impact on page load speeds. However recurring requests (using `statusCheckInterval`) may run more slowly if the interval between requests is very short.

src/components/LinkItems/Item.vue

@@ -67,6 +67,8 @@ export default {
     },
     itemSize: String,
     enableStatusCheck: Boolean,
+    statusCheckHeaders: Object,
+    statusCheckUrl: String,
     statusCheckInterval: Number,
   },
   data() {
@@ -141,8 +143,10 @@ export default {
     checkWebsiteStatus() {
       this.statusResponse = undefined;
       const baseUrl = process.env.VUE_APP_DOMAIN || window.location.origin;
-      const endpoint = `${baseUrl}/ping?url=${this.url}`;
-      axios.get(endpoint)
+      const urlToCheck = this.statusCheckUrl || this.url;
+      const headers = this.statusCheckHeaders || {};
+      const endpoint = `${baseUrl}/ping?url=${urlToCheck}`;
+      axios.get(endpoint, { headers })
         .then((response) => {
           if (response.data) this.statusResponse = response.data;
         })

src/components/LinkItems/ItemGroup.vue

@@ -27,6 +27,8 @@
         :target="item.target"
         :color="item.color"
         :backgroundColor="item.backgroundColor"
+        :statusCheckUrl="item.statusCheckUrl"
+        :statusCheckHeaders="item.statusCheckHeaders"
         :itemSize="newItemSize"
         :enableStatusCheck="shouldEnableStatusCheck(item.statusCheck)"
         :statusCheckInterval="getStatusCheckInterval()"

src/utils/ConfigSchema.json

@@ -341,6 +341,14 @@
                   "type": "boolean",
                   "default": false,
                   "description": "Whether or not to display online/ offline status for this service. Will override appConfig.statusCheck"
+                },
+                "statusCheckUrl": {
+                  "type": "string",
+                  "description": "If you've enabled statusCheck, and want to use a different URL to what is defined under the item, then specify it here"
+                },
+                "statusCheckHeaders": {
+                  "type": "object",
+                  "description": " If you're endpoint requires any specific headers for the status checking, then define them here"
                 }
               }
             }