Dashund / dachshund
Tools for making dashboards as simple and quick as possible
Table of contents
What is this?
Dashund is a framework for creating dashboards, aiming at doing the boring parts of authenticating and connecting RESTful APIs together and re-serving content.
Say you connect to Spotify to get songs using their RESTful API
and you want to show whats playing on a screen.
You create a Token
in Dashund to handle the auth process
and an Endpoint
to poll for data at a set interval.
You use the CLI to create an authentication using your Token
.
Then you run dashund as a server which performs your Endpoint
s using those tokens
(re-authenticating when needed) and re-serve the responses over http and publish WebSocket
events.
The CLI is designed to be run accross SSH so you can perform web-based hooks on your local machine and store the values on your remote server. I.E. doing a OAuth2 web flow and storing the tokens back on the server
Your web app can now initially fetch the value using the http API and subscribe to WebSocket events to be pushed new values.
Project components
- A CLI for managing widgets within zones
- A CLI for authenticating with 3rd party services and storing access tokens
- An API for reading in widgets, zones and tokens
- An API for scaffolding an http JSON RESTful API
- An API for scaffolding a socket based subscription to endpoints
- UI utilities to subscribe to the sockets (WIP)
- UI components for rendering widgets in zones (WIP)
File structure
Dashund stores access tokens and widgets locally, wherever you are running it,
in a folder called .dashund
dashund.js # module.exports = new Dashund(...) cli.js # imports dashund and calls runCLI(...) server.js # imports dashund and calls runServer(...) .dashund widgets.yml # YAML config for where widgets are stored tokens.json # JSON config for access tokens
The CLI
The CLI is designed to be interactive-first, to provide the best human experience.
Its inspired by kubernete's resource-based approach with the resources being
Token
, Widget
and Zone
.
Usage: dashund <command>
Commands:
cli.js get Display resources
cli.js create [type] Create a new resource
cli.js check Check token authentication
cli.js serve [port] Run the dashund server
Options:
--version Show version number [boolean]
--help, -h Show help [boolean]
--path The path where your .dashund folder is [default: cwd]
The API
A Token
First you'll want a token, a factory for authenticating to a 3rd party service, e.g. tokens.js
const runTemporaryServer = const axios = exportsGitHub = // // A method for creating the token, with user input // and potentially a temporary server for handling callbacks // async { const callbackURL = dashund console let token = null await return token } // // A second method for letting dashund know when that token has expired // { return tokenexpiresAt < Date } // // A third method for re-authenticating if a token becomes invalid / expires // - This can't have user input // async { let res = await axios return resdata }
A Widget
Second you'll need a widget which will render things on the front end, e.g. widgets.js
exportsGitHubActivity = requiredEndpoints = 'github/activity' { return title } async { const title = await return title }
An endpoint
Third create endpoints which use the tokens to fetch data, e.g. endpoints.js
const axios = moduleexports = name: 'github/activity' requiredTokens: 'GitHub' interval: '5m' handler: async { let accessToken = ctxtokens let headers = authorization: `Bearer ` let res = await axios return resdata }
Configuring dashund
Next, create your instance, e.g. dashund.js
const Dashund = // Import your token and widget factories and endpointsconst widgets = const tokens = const endpoints = // Export an instance of Dashundmoduleexports = widgets tokens endpoints
Then create a CLI entrypoint, cli.js
const dashund = dashund
Finally create a server entrypoint, server.js
const dashund = ;async { await dashund console}
Now you can run the cli with node cli.js
and the server with node server.js
.
Example usage
Here are some example requests with httpie
# Fetch a specify resource, calling it's handler http https://dashboard.io/github/activity
Example socket subscriptions with akita-ws:
akita wss://dashboard.io> {"type": "sub", "name": "github/activity"}> {"type": "unsub", "name": "github/activity"}
Extra configuration
After the widgets, tokens and endpoints you can also pass an extra options
object to configure dashund more.
path
is the relative path to your.dashund
folderhostname
is the hostname the cli will appear as when authenticating tokenscorsHosts
is an array of hosts that the server will accept cors requests fromauthenticator
is a function to authenticate some requests and all sockets, it gets passed an http.IncomingMessage