@domoinc/ryuu-proxy
v4.4.0
Published
a middleware that provides a proxy for local domo app development
Downloads
639
Readme
ryuu-proxy
Simple middleware to add to a local development server while developing Domo Apps. The middleware will intercept any calls to /data/v{d}
, /sql/v{d}
, /dql/v{d}
or /domo/.../v{d}
, proxy an authenticated request to the Domo App service, and pipe the response back so that you can develop your Domo App locally and still get request data from Domo.
Installation
npm install @domoinc/ryuu-proxy --save-dev
Usage
This library leverages the last login session from your Domo CLI. If that session is no longer active or doesn't exist then the proxy won't work. Be sure that you've logged in before you start working:
$ domo login
Configuration
const { Proxy } = require("@domoinc/ryuu-proxy");
const manifest = require("./path/to/app/manifest.json");
const config = { manifest };
// use `proxy` in your development server
const proxy = new Proxy(config);
The proxy constructor expects a config
object. Certain properties are required and others are optional.
Required Configuration Properties
manifest
: The parsed contents of a project's manifest.json file.domo publish
have been run at least once to ensure themanifest.json
file has anid
property
Optional Configuration Properties
manifest.proxyId
: An advanced property required for projects leveraging DQL, writebacks, or Oauth. If you are unsure of whether or not you need this, you most likely don't. To get a proxyId, see "Getting a proxyId" below
With Express / Connect
This library comes with a simple wrapper for Express/Connect middleware.
const app = express();
app.use(proxy.express());
With Other Frameworks
For other frameworks, the library exposes the necessary functions to create a stream to pipe back to your server. You'll need to handle this stream as your server would expect. The only thing that stream()
expects is a standard Node Request which most server frameworks extend in some way.
// koa
app.use(async (ctx, next) => {
await proxy
.stream(ctx.req)
.then((data) => (ctx.body = ctx.req.pipe(data)))
.catch(next);
});
// express
app.use((req, res, next) => {
proxy
.stream(req)
.then((stream) => stream.pipe(res))
.catch(() => next());
});
// node http
const server = http.createServer((req, res) => {
if (req.url === "/") {
loadHomePage(res);
} else {
proxy.stream(req).then((stream) => stream.pipe(res));
}
});
Error Handling
Ignoring the errors will cause the proxy to fail silently and the proxy request will return a 404
error. If you'd like a little more detail on the errors you can expose them in the response:
// koa
app.use(async (ctx, next) => {
await proxy
.stream(ctx.req)
.then((data) => (ctx.body = ctx.req.pipe(data)))
.catch((err) => {
if (err.name === "DomoException") {
ctx.status = err.status || err.statusCode || 500;
ctx.body = err;
} else {
next();
}
});
});
// express / connect
app.use((req, res, next) => {
proxy
.stream(req)
.then((stream) => stream.pipe(res))
.catch((err) => {
if (err.name === "DomoException") {
res.status(err.status || err.statusCode || 500).json(err);
} else {
next();
}
});
});
// http
const server = http.createServer((req, res) => {
if (req.url === "/") {
loadHomePage();
} else {
proxy
.stream(req)
.then((stream) => stream.pipe(res))
.catch((err) => {
if (err.name === "DomoException") {
res.writeHead(err.status || err.statusCode || 500);
res.end(JSON.stringify(err));
}
});
}
});
Getting a proxyId (Advanced)
Apps using DQL, writeback, or oAuth features are required to supply an proxyId as part of the proxy configuration. This allows the proxy to know how to properly route requests. The proxyId can be found as part of the URL for the iframe in which your app is displayed. It will be of the form XXXXXXXX-XXXX-4XXX-XXXX-XXXXXXXXXXXX
. To find the ID:
- Make sure the app has been published at least once with
domo publish
- Publish a new card based on your app design, or navigate to an existing card made from your app design
- Right-click anywhere in the card and choose "Inspect element"
- Find the
<iframe>
that contains your app's code. The URL should be of the form//{HASH}.domoapps.prodX.domo.com?userId=...
- Copy the ID found between
//
and.domoapps
. That is your app'sproxyId
proxyId
s tie apps to cards. If you delete the card from which you retrieved the proxyId, you will have to get a new one from another card created from your app design.
Building
To build ryuu-proxy, run
npm run build
All necessary files will be built/copied into the dist
folder.
Contributing
Recommended Workflow:
- Create new branch (named "DOMO-XXXXXX")
- Make Changes
- Commit Changes
- Test changes (if necessary, version a alpha/beta/tagged version, then release it)
- Make pull request
- After pull request is merged to master, bump version, then release it to npm
Versioning
This project utilizes standard-version.
npm run bump
- Version bumps determined automatically via commitsnpm run bumpBeta
ornpm run bump -- --prerelease beta
- 4.0.x-beta.0 (if no current beta) or 4.0.0-beta.x (if current beta exists)
Releasing
Versions should be released on npm
npm run release
npm run releaseAlpha
npm run releaseBeta