@domoinc/ryuu-proxy

Middleware for local Domo App development. It intercepts calls to Domo data/API endpoints and proxies authenticated requests to your Domo instance, so you can develop against real data from your local dev server.

Table of Contents

• Features
• Requirements
• Installation
• Usage
  • Configuration
  • Express / Connect
  • Other Frameworks
  • Error Handling
• HTTP Proxy Support
• Getting a proxyId
• Contributing
• License

Features

• Intercepts and proxies Domo API traffic: /data/v{d}, /sql/v{d}, /dql/v{d}, /domo/.../v{d}, /api/...
• Drop-in Express / Connect middleware via proxy.express()
• Framework-agnostic proxy.stream(req) for Koa, Node http, Fastify, etc.
• Handles multipart/form-data uploads (file streams via busboy)
• Injects OAuth access/refresh tokens for apps using DQL, writeback, or OAuth features
• Reads auth from your existing Domo CLI login session — no extra config
• Ships with TypeScript types
• ESM package

Requirements

• Node.js 18+
• An active Domo CLI session (domo login) — see @ryuu
• A project manifest.json that has been published at least once (domo publish)
• Peer: express ^4.17.0 || ^5.0.0 (only required if you use proxy.express())

Installation

pnpm add -D @domoinc/ryuu-proxy
# or
npm install --save-dev @domoinc/ryuu-proxy
# or
yarn add -D @domoinc/ryuu-proxy

Usage

This library leverages the last login session from your Domo CLI. If that session is no longer active or doesn't exist, the proxy won't work. Log in before starting your dev server:

domo login

Configuration

import { Proxy } from '@domoinc/ryuu-proxy';
import manifest from './path/to/app/manifest.json' with { type: 'json' };

const proxy = new Proxy({ manifest });

The Proxy constructor accepts a config object.

Required

• manifest — parsed contents of your project's manifest.json. domo publish must have been run at least once so the manifest has an id.

Optional

• manifest.proxyId — required for apps using DQL, writebacks, or OAuth. If you're unsure, you probably don't need it. See Getting a proxyId.

With Express / Connect

import express from 'express';

const app = express();
app.use(proxy.express());

With Other Frameworks

For other frameworks, stream() returns a readable stream you can pipe back to your response. It accepts a standard Node IncomingMessage, which most frameworks extend.

// 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
import http from '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 errors causes the proxy to fail silently and the request returns 404. To expose errors, catch DomoException and forward the status:

// 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();
      }
    });
});

// node 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));
        }
      });
  }
});

DomoException shape:

| Field | Description | | ----------------------- | ------------------------ | | name | Always "DomoException" | | status / statusCode | HTTP status code | | statusMessage | Error description |

HTTP Proxy Support

If you sit behind a corporate HTTP proxy, set any of the following environment variables. REACT_APP_-prefixed variants are also honored for Create React App projects.

| Variable | Purpose | | --------------------------------------------- | ------------------------------ | | PROXY_HOST / REACT_APP_PROXY_HOST | Proxy hostname | | PROXY_PORT / REACT_APP_PROXY_PORT | Proxy port | | PROXY_USERNAME / REACT_APP_PROXY_USERNAME | Basic auth username (optional) | | PROXY_PASSWORD / REACT_APP_PROXY_PASSWORD | Basic auth password (optional) |

Getting a proxyId (Advanced)

Apps using DQL, writeback, or OAuth features must supply a proxyId in the proxy configuration so the proxy can route requests correctly. A proxyId is of the form XXXXXXXX-XXXX-4XXX-XXXX-XXXXXXXXXXXX. To find it:

1. Ensure the app has been published at least once with domo publish.
2. Publish a new card from your app design, or open an existing card built from it.
3. Right-click the card and choose Inspect element.
4. Find the <iframe> containing your app. Its URL looks like //{HASH}.domoapps.prodX.domo.com?userId=....
5. Copy the hash between // and .domoapps — that is your proxyId.

proxyIds tie apps to cards. If you delete the card you pulled the ID from, you'll need a new one from another card created from the same app design.

Related Packages

• ryuu — the Domo CLI (domo login, domo publish, etc.)
• ryuu-client — underlying Domo API client

Contributing

Workflow

1. Create a branch (e.g. DOMO-XXXXXX)
2. Make and commit changes
3. Test — optionally publish an alpha/beta for integration testing
4. Open a pull request
5. After merge to master, bump the version and release to npm

Scripts

| Script | Description | | ----------------------------- | --------------------------------------- | | pnpm run build | Compile TypeScript to dist/ | | pnpm test | Run the test suite (vitest) | | pnpm run test:watch | Run vitest in watch mode | | pnpm run test:coverage | Run tests with coverage | | pnpm run format | Format source with Prettier | | pnpm run release:production | Build and publish to npm | | pnpm run release:beta | Build and publish under the beta tag | | pnpm run release:alpha | Build and publish under the alpha tag |

Versioning

This project uses standard-version with conventional commits to determine version bumps.

License

MIT