@siteone/preview-vhost-client

Thin client for a preview-be style vhost management API: get a port, create a vhost, delete a vhost.

This package exists so that repos deploying preview environments don't each duplicate the HTTP calls, DNS-label-length workaround, and delete-retry logic for talking to their preview-be instance. Consuming repos should only ever need to call "create vhost" / "delete vhost" (and whatever else preview-be grows) — no http module, no URL building, no knowledge of DNS label limits.

This package intentionally contains no specific hostname, port, or domain of any real instance — not even in this README's examples. It ships publicly on npm, so any project-specific infrastructure details belong in the (private) consuming repo's own config, not here.

Written in TypeScript, published as compiled CommonJS with bundled .d.ts type definitions — works from both TS and plain JS consumers (e.g. a deploy.config.js) via a normal require(...).

Install

yarn add @siteone/preview-vhost-client

Development

npm install
npm run build   # compiles src/ (TypeScript) -> dist/ (CommonJS + .d.ts)
npm test        # runs test/index.test.ts directly via tsx, no build needed

Usage

Create a client once with your instance's details, then just call createVhost/deleteVhost:

const { createClient } = require('@siteone/preview-vhost-client')

const previewVhostClient = createClient({
  hostname: '<your preview-be hostname>',
  port: '<your preview-be port>',
  domainSuffix: '<your preview domain suffix, e.g. .preview.example.com>',
  logger: log, // optional, defaults to console
})

// Get a port / create the vhost
const { port, name } = await previewVhostClient.createVhost({
  name: `${appName}${domainSuffix}`,
  branch: tag,
  commitAuthor: process.env.CI_TOOLS_COMMIT_AUTHOR,
  commitDate: dynamicArgs.commitDate.toISOString(),
  commitMessage: process.env.CI_TOOLS_COMMIT_MESSAGE,
  buildAuthor: process.env.GITLAB_USER_LOGIN,
})

// ... later, on stop:
await previewVhostClient.deleteVhost(appName)

deleteVhost internally retries with a shortened DNS-label lookup name if the full app name is too long for preview-be to resolve.

Configuration

createClient(config) (and the standalone functions below, which take the same config as their last argument) require:

{
  hostname,       // required
  port,           // required
  domainSuffix,   // required
  lookupLabelMax, // optional, defaults to 58
  logger,         // optional, defaults to console; needs .info(...) and .warn(...)
  transport,      // optional, defaults to an http.request-based transport (for tests)
}

hostname/port/domainSuffix are intentionally not defaulted and will throw a clear error if omitted -- this package ships publicly on npm and shouldn't assume or embed any specific project's internal infrastructure address in its source (or in this README).

Standalone functions

If you don't want to create a client, every function also accepts the same config as its last argument directly: createVhost(postData, config), deleteVhost(appName, config), etc.

Low-level API

For anything not covered by the high-level helpers, the raw one-to-one wrappers around preview-be's endpoints are also exported:

• createDomain(postData, config) – POST /api/v1/domain
• deleteDomain(name, config) – DELETE /api/v1/domain/:name
• getDomainLookupNames(appName, config) – the full name + shortened fallback
• isVhostDeleted(body) – interprets a preview-be response body

Migrating a consuming repo

1. yarn add @siteone/preview-vhost-client, delete the repo's local vhost-api.js.

2. In deploy.config.js, create a client once, passing in that repo's own real hostname/port/domainSuffix (this is where those details live now — in the private repo, not in this public package or its docs):

   const { createClient } = require('@siteone/preview-vhost-client')
   
   const previewVhostClient = createClient({
     hostname: /* your real preview-be host */,
     port: /* your real preview-be port */,
     domainSuffix: /* your real preview domain suffix */,
     logger: log,
   })

3. Replace getPreviewDomainLookupNames, isPreviewVhostDeleted, and the body of deleteVhost/getPreviewPort with calls to previewVhostClient.deleteVhost(appName) / previewVhostClient.createVhost(postData). Keep tag parsing, app-name prefixing, and APP_DOMAIN/.env handling in the repo — that part is deploy-flow specific, not preview-be-specific.

Publishing

npm version <patch|minor|major>
npm publish

Requires npm account access to the @siteone org.