push2cloud-cf-adapter

This repository is part of the push2cloud project. For contribution guidelines, issues, and general documentation, visit the main push2cloud project page.

push2cloud-cf-adapter abstracts the cloud foundry api. It's designed for use with Node.js and installable via npm install --save push2cloud-cf-adapter.

Usage

const cf = require('push2cloud-cf-adapter');
 
const api = cf({
  api: process.env.CF_API || 'https://api.lyra-836.appcloud.swisscom.com',
  username: process.env.CF_USER,
  password: process.env.CF_PWD,
  org: process.env.CF_ORG,
  space: process.env.CF_SPACE
});
 
// the callback way...
api.init((err, result) => {
  api.pushApp({
    name: 'temp-app',
    path: '/path/to/sampleApp'
  }, (err, app) => {
    api.stageApp({
      appGuid: app.metadata.guid
      // or: name: 'temp-app'
    }, (err) => {
      api.startAppAndWaitForInstances({
        appGuid: app.metadata.guid
        // or: name: 'temp-app'
      }, (err) => {
        // ...
      });
    });
  });
});
 
// or the promise way...
api.init()
.then((app) => {
  return api.pushApp({
    name: 'temp-app',
    path: '/path/to/sampleApp'
  });
})
.then((app) => {
  return api.stageApp({
    appGuid: app.metadata.guid
    // or: name: 'temp-app'
  });
})
.then(() => {
  return api.startAppAndWaitForInstances({
    appGuid: app.metadata.guid
    // or: name: 'temp-app'
  });
})
.then(() => {
  // ...
});
 

Download

The source is available for download from GitHub. Alternatively, you can install using npm:

npm install --save push2cloud-cf-adapter

You can then require() push2cloud-cf-adapter as normal:

const cf = require('push2cloud-cf-adapter');

Documentation

Each asynchronous call can be done with classical callback style or with promise style.

General

• init
• getInfo
• stats
• attachRetryHandler

App

• createApp
• uploadApp
• pushApp
• stageApp
• startApp
• stopApp
• restartApp
• startAppAndWaitForInstances
• deleteApp

Route

• createRoute
• associateRoute
• disassociateRoute
• deleteRoute

Service

• createServiceInstance
• bindService
• unbindService
• deleteServiceInstance

General

General api methods.

init([callback])

Retrieves information of the current space. i.e. apps, services, service bindings, routes, domains, etc...

Arguments

• callback(err, result) - A callback which is called when function has finished, or an error occurs.

Example

const cf = require('push2cloud-cf-adapter');
 
const api = cf({
  api: 'https://the-url-to-the-cloud-foundry-api-endpoint',
  username: 'my-funny-username',
  password: 'my-very-secret-password',
  org: 'the-cf-org',
  space: 'the-cf-space',
  rejectUnauthorized: true, // optional
  maxRetries: 3, // optional
  delay: 1000, // optional
  delayFactor: 1 // optional
});
 
api.init((err, result) => {
  console.log(result);
  // {
  //   "apps": [
  //     {
  //       "name": "push2cloud-example-api-1.0.0",
  //       "unversionedName": "push2cloud-example-api",
  //       "guid": "cff85cc4-e217-47f0-b0e0-113d04e6e37d",
  //       "instances": 1,
  //       "memory": 512,
  //       "disk": 512,
  //       "state": "STARTED",
  //       "version": "1.0.0",
  //       "package_state": "STAGED"
  //     },
  //     {
  //       "name": "push2cloud-example-host-2.0.0",
  //       "unversionedName": "push2cloud-example-host",
  //       "guid": "9afc0b68-9004-4292-9284-6110bed72afb",
  //       "instances": 1,
  //       "memory": 512,
  //       "disk": 1024,
  //       "state": "STARTED",
  //       "version": "2.0.0",
  //       "package_state": "STAGED"
  //     }
  //   ],
  //   "serviceBindings": [
  //     {
  //       "service": "todo-db",
  //       "serviceInstanceGuid": "e0dc3f5e-7631-473e-ad3e-ebbf0549ad22",
  //       "app": "push2cloud-example-api-1.0.0",
  //       "unversionedName": "push2cloud-example-api",
  //       "appGuid": "cff85cc4-e217-47f0-b0e0-113d04e6e37d",
  //       "guid": "0d82e751-26ab-40b1-987a-8e1671b39c24"
  //     }
  //   ],
  //   "services": [
  //     {
  //       "name": "todo-db",
  //       "guid": "e0dc3f5e-7631-473e-ad3e-ebbf0549ad22",
  //       "type": "redis",
  //       "plan": "small"
  //     }
  //   ],
  //   "routes": [
  //     {
  //       "guid": "bd7cb2eb-f9fe-4b84-a7cd-1f43969e3ba9",
  //       "domain": "scapp.io",
  //       "domainGuid": "5f952bf2-618b-4584-b37e-92e406149285",
  //       "hostname": "push2cloud-example-host-iot-cf-test",
  //       "app": "push2cloud-example-host-2.0.0",
  //       "unversionedName": "push2cloud-example-host",
  //       "appGuid": "9afc0b68-9004-4292-9284-6110bed72afb"
  //     },
  //     {
  //       "guid": "47542223-1a74-45e9-8857-7baab1b29941",
  //       "domain": "scapp.io",
  //       "domainGuid": "5f952bf2-618b-4584-b37e-92e406149285",
  //       "hostname": "push2cloud-example-api-iot-cf-test",
  //       "app": "push2cloud-example-api-1.0.0",
  //       "unversionedName": "push2cloud-example-api",
  //       "appGuid": "cff85cc4-e217-47f0-b0e0-113d04e6e37d"
  //     }
  //   ],
  //   "envVars": [
  //     {
  //       "env": {
  //         "SYSTEM_VERSION": "1.0.0"
  //       },
  //       "name": "push2cloud-example-api-1.0.0",
  //       "unversionedName": "push2cloud-example-api"
  //     },
  //     {
  //       "env": {
  //         "SYSTEM_VERSION": "1.0.0",
  //         "PUSH2CLOUD_EXAMPLE_API_HOST": "https://push2cloud-example-api-iot-cf-test.scapp.io"
  //       },
  //       "name": "push2cloud-example-host-2.0.0",
  //       "unversionedName": "push2cloud-example-host"
  //     }
  //   ],
  //   "domains": [
  //     {
  //       "guid": "5f952bf2-618b-4584-b37e-92e406149285",
  //       "name": "scapp.io"
  //     },
  //     {
  //       "guid": "dc478cd0-5185-4a48-a964-1e53d868daf2",
  //       "name": "applicationcloud.io"
  //     }
  //   ]
  // }
});

---

getInfo([callback])

Retrieves information of the cloud foundry platform.

Arguments

• callback(err, result) - A callback which is called when function has finished, or an error occurs.

Example

api.getInfo((err, result) => {
  console.log(result);
  // {
  //   "name": "",
  //   "build": "",
  //   "support": "https://developer.swisscom.com/contact",
  //   "version": 0,
  //   "description": "Cloud Foundry provided by Swisscom",
  //   "authorization_endpoint": "https://login.lyra-836.appcloud.swisscom.com",
  //   "token_endpoint": "https://uaa.lyra-836.appcloud.swisscom.com",
  //   "min_cli_version": null,
  //   "min_recommended_cli_version": null,
  //   "api_version": "2.52.0",
  //   "app_ssh_endpoint": "ssh.lyra-836.appcloud.swisscom.com:2222",
  //   "app_ssh_host_key_fingerprint": "6d:d2:8c:09:64:b6:fc:2b:50:3c:a9:cb:2e:be:d4:a7",
  //   "app_ssh_oauth_client": "ssh-proxy",
  //   "logging_endpoint": "wss://loggregator.lyra-836.appcloud.swisscom.com:443",
  //   "doppler_logging_endpoint": "wss://doppler.lyra-836.appcloud.swisscom.com:443"
  // }
});

---

stats.on('retry', [fn])

Will be emitted when an api request will retry.

Arguments

• fn(obj) - A function which is called when an api request will retry.

Example

api.stats.on('retry', (obj) => {
  console.log(obj);
  // {
  //   "error": null,
  //   "response": { "statusCode": "500" /* rest of the response object */ },
  //   "result": {
  //     "code": 10011,
  //     "description": "Database error",
  //     "error_code": "CF-DatabaseError"
  //   },
  //   "attempt": 1,
  //   "infos": {
  //     "method": "POST",
  //     "uri": "/v2/service_instances",
  //     "json": {
  //       "name": "my-db",
  //       "space_guid": "7d8bf5be-a793-472b-8a84-78b04cc03864",
  //       "service_plan_guid": "0ad5b617-0a32-4a24-ba24-216f191ab9ef",
  //       "parameters": {},
  //       "tags": []
  //     },
  //     "qs": { "accepts_incomplete": true },
  //     "baseUrl": "https://api.lyra-836.appcloud.swisscom.com",
  //     "rejectUnauthorized": true,
  //     "headers": { "Authorization": "bearer eyJ..." }
  //   },
  //   "reason": "Database error"
  // }
});

---

api.attachRetryHandler([fn])

You can attach you own retryHandler for your target.

Arguments

• fn(options) - A function or an array of funcitons which is called to verify if the failed request should be retried. Should return true or a string to trigger a retry.

Examples

api.attachRetryHandler((options) => {
  // const err = options.error;
  // const response = options.response;
  const result = options.result;
  const infos = options.infos;
  // const attempt = options.attempt;
 
  if (infos.uri.indexOf('/service_bindings') >= 0) {
    if (result && result.error_code && result.error_code === 'UnknownError') {
      return result.description || 'An unknown error occurred';
    }
  }
 
  if (infos.uri.indexOf('/service_instances') >= 0) {
    if (result && result.code === 10011) {
      return result.error_description;
    }
  }
});

api.attachRetryHandler([
  (options) => {
    // const err = options.error;
    // const response = options.response;
    const result = options.result;
    const infos = options.infos;
    // const attempt = options.attempt;
 
    if (infos.uri.indexOf('/service_bindings') >= 0) {
      if (result && result.error_code && result.error_code === 'UnknownError') {
        return result.description || 'An unknown error occurred';
      }
    }
  },
  (options) => {
    // const err = options.error;
    // const response = options.response;
    const result = options.result;
    const infos = options.infos;
    // const attempt = options.attempt;
 
    if (infos.uri.indexOf('/service_instances') >= 0) {
      if (result && result.code === 10011) {
        return result.error_description;
      }
    }
  }
]);

---

App

App related api methods.

createApp(options, [callback])

Creates an app.

Arguments

• options - An options containing:
  • name - The app name.
  • buildpack - Optional Buildpack to build the app. 3 options:
    • a) Blank or not set means autodetection.
    • b) A Git Url pointing to a buildpack.
    • c) Name of an installed buildpack.
  • command - Optional The command to start an app after it is staged, maximum length: 4096 (e.g. 'rails s -p $PORT' or 'java com.org.Server $PORT').
  • env - Optional Object containing key/value pairs of all the environment variables to run in your app. Does not include any system or service variables.
  • disk - Optional The maximum amount of disk available to an instance of an app. i.e. 256MB, 1G, 256, 1024
  • memory - Optional The amount of memory each instance should have. i.e. 256MB, 1G, 256, 1024
  • instances - Optional The number of instances of the app to run. To ensure optimal availability, ensure there are at least 2 instances.
  • dockerImage - Optional Name of the Docker image containing the app.
  • enableSSH - Optional Enable SSHing into the app. Supported for Diego only. false if SSH is disabled globally or on the space, true if enabled for both
  • healthCheckType - Optional Type of health check to perform. 'port' or 'process'
  • healthCheckTimeout - Optional Timeout for health checking of an staged app when starting up
• callback(err, result) - A callback which is called when function has finished, or an error occurs.

Example

api.createApp({
  name: 'temp-app'
}, (err, result) => {});

---

uploadApp(options, [callback])

Uploads an app.

Arguments

• options - An options containing:
  • appGuid - Optional The app guid. appGuid or name are mandatory but not both.
  • name - Optional The app name. appGuid or name are mandatory but not both.
  • path - The path to the app on your filesystem.
  • tmpZipPath - Optional Custom temporary path to save the zip file. Default is path + '.zip.tmp'.
• callback(err, result) - A callback which is called when function has finished, or an error occurs.

Example

api.uploadApp({
  path: '/path/to/sampleApp'
}, (err, result) => {});

---

pushApp(options, [callback])

Creates and uploads an app.

Arguments

• options - See combined options argument of createApp and uploadApp.
• callback(err, result) - A callback which is called when function has finished, or an error occurs.

Example

api.pushApp({
  name: 'temp-app',
  path: '/path/to/sampleApp'
}, (err, result) => {});

---

stageApp(options, [callback])

Stages an app. Creates a droplet so the effective start of that app will be much faster.

Arguments

• options - An options containing:
  • appGuid - Optional The app guid. appGuid or name are mandatory but not both.
  • name - Optional The app name. appGuid or name are mandatory but not both.
  • stageTimeout - Optional Will return if staging duration is longer than that value in seconds. Default is 300.
• callback(err, result) - A callback which is called when function has finished, or an error occurs.

Example

api.stageApp({
  name: 'temp-app'
}, (err, result) => {});

---

startApp(options, [callback])

Starts an app.

Arguments

• options - An options containing:
  • appGuid - Optional The app guid. appGuid or name are mandatory but not both.
  • name - Optional The app name. appGuid or name are mandatory but not both.
• callback(err, result) - A callback which is called when function has finished, or an error occurs.

Example

api.startApp({
  name: 'temp-app'
}, (err, result) => {});

---

stopApp(options, [callback])

Stops an app.

Arguments

• options - An options containing:
  • appGuid - Optional The app guid. appGuid or name are mandatory but not both.
  • name - Optional The app name. appGuid or name are mandatory but not both.
• callback(err, result) - A callback which is called when function has finished, or an error occurs.

Example

api.stopApp({
  name: 'temp-app'
}, (err, result) => {});

---

restartApp(options, [callback])

Restarts an app.

Arguments

• options - An options containing:
  • appGuid - Optional The app guid. appGuid or name are mandatory but not both.
  • name - Optional The app name. appGuid or name are mandatory but not both.
• callback(err, result) - A callback which is called when function has finished, or an error occurs.

Example

api.restartApp({
  name: 'temp-app'
}, (err, result) => {});

---

startAppAndWaitForInstances(options, [callback])

Starts an app and waits for all instances to run stable.

Arguments

• options - An options containing:
  • appGuid - Optional The app guid. appGuid or name are mandatory but not both.
  • name - Optional The app name. appGuid or name are mandatory but not both.
  • startTimeout - Optional Will return if starting duration is longer than that value in seconds. Default is 30.
  • interval - Optional The interval in seconds to wait between checking the app instance state. Default is 3.
  • timeout - Optional Will return if starting duration of a single instance is longer than that value in seconds. Default is 30.
  • gracePeriod - Optional Period to check and wait for the app instances not crashing. Default is 40.
• callback(err, result) - A callback which is called when function has finished, or an error occurs.

Example

api.startAppAndWaitForInstances({
  name: 'temp-app'
}, (err, result) => {});

---

deleteApp(options, [callback])

Deletes an app.

Arguments

• options - An options containing:
  • appGuid - Optional The app guid. appGuid or name are mandatory but not both.
  • name - Optional The app name. appGuid or name are mandatory but not both.
• callback(err, result) - A callback which is called when function has finished, or an error occurs.

Example

api.deleteApp({
  name: 'temp-app'
}, (err, result) => {});

---

Route

Route related api methods.

createRoute(options, [callback])

Creates a route.

Arguments

• options - An options containing:
  • domainGuid - Optional The app guid. domainGuid or domain are mandatory but not both.
  • domain - Optional The app name. domainGuid or domain are mandatory but not both.
  • hostname - The host portion of the route. Required for shared-domains.
  • path - The path for a route as raw text. 1) Paths must be between 2 and 128 characters 2) Paths must start with a forward slash "/" 3) Paths must not contain a "?"
  • port - The port of the route. Supported for domains of TCP router groups only.
  • generatePort - Set to true to generate a random port. Defaults to false. Supported for domains for TCP router groups only. Takes precedence over manually specified port.
• callback(err, result) - A callback which is called when function has finished, or an error occurs.

Example

api.createRoute({
  hostname: 'my-app',
  domain: 'applicationcloud.io'
}, (err, result) => {});

---

associateRoute(options, [callback])

Associates a route to an app.

Arguments

• options - An options containing:
  • appGuid - Optional The app guid. appGuid or app are mandatory but not both.
  • app - Optional The app name. appGuid or app are mandatory but not both.
  • routeGuid - Optional The route guid. routeGuid or domain and hostname are mandatory but not all.
  • domain - Optional The app name. routeGuid or domain and hostname are mandatory but not all.
  • hostname - Optional The host portion of the route. Required for shared-domains. routeGuid or domain and hostname are mandatory but not all.
• callback(err, result) - A callback which is called when function has finished, or an error occurs.

Example

api.associateRoute({
  app: 'temp-app',
  hostname: 'my-app',
  domain: 'applicationcloud.io'
}, (err, result) => {});

---

disassociateRoute(options, [callback])

Disassociates a route from an app.

Arguments

• options - An options containing:
  • appGuid - Optional The app guid. appGuid or app are mandatory but not both.
  • app - Optional The app name. appGuid or app are mandatory but not both.
  • routeGuid - Optional The route guid. routeGuid or domain and hostname are mandatory but not all.
  • domain - Optional The app name. routeGuid or domain and hostname are mandatory but not all.
  • hostname - Optional The host portion of the route. Required for shared-domains. routeGuid or domain and hostname are mandatory but not all.
• callback(err, result) - A callback which is called when function has finished, or an error occurs.

Example

api.disassociateRoute({
  app: 'temp-app',
  hostname: 'my-app',
  domain: 'applicationcloud.io'
}, (err, result) => {});

---

deleteRoute(options, [callback])

Deletes a route.

Arguments

• options - An options containing:
  • routeGuid - Optional The route guid. routeGuid or domain and hostname are mandatory but not all.
  • domain - Optional The app name. routeGuid or domain and hostname are mandatory but not all.
  • hostname - Optional The host portion of the route. Required for shared-domains. routeGuid or domain and hostname are mandatory but not all.
• callback(err, result) - A callback which is called when function has finished, or an error occurs.

Example

api.deleteRoute({
  app: 'temp-app',
  hostname: 'my-app',
  domain: 'applicationcloud.io'
}, (err, result) => {});

---

Service

Service related api methods.

createServiceInstance(options, [callback])

Creates a service instance.

Arguments

• options - An options containing:
  • name - The service instance name.
  • type - The service type.
  • plan - The service plan.
  • parameters - Optional Arbitrary parameters to pass along to the service broker. Must be an object.
  • tags - Optional An array of strings for the service instance. Max characters: 2048
• callback(err, result) - A callback which is called when function has finished, or an error occurs.

Example

api.createServiceInstance({
  name: 'my-db',
  type: 'mongodb',
  plan: 'small'
}, (err, result) => {});

---

bindService(options, [callback])

Binds a service instance to an app.

Arguments

• options - An options containing:
  • appGuid - Optional The app guid. appGuid or app are mandatory but not both.
  • app - Optional The app name. appGuid or app are mandatory but not both.
  • service - Optional The service instance name. serviceInstanceGuid or service are mandatory but not both.
  • serviceInstanceGuid - Optional The service instance guid. serviceInstanceGuid or service are mandatory but not both.
  • parameters - Optional Arbitrary parameters to pass along to the service broker. Must be an object.
• callback(err, result) - A callback which is called when function has finished, or an error occurs.

Example

api.bindService({
  app: 'temp-app',
  service: 'my-db'
}, (err, result) => {});

---

unbindService(options, [callback])

Unbinds a service instance from an app.

Arguments

• options - An options containing:
  • app - Optional The app name. serviceBindingGuid or app and service` are mandatory but not all.
  • service - Optional The service instance name. serviceBindingGuid or app and service` are mandatory but not all.
  • serviceBindingGuid - Optional serviceBindingGuid or app and service` are mandatory but not all.
• callback(err, result) - A callback which is called when function has finished, or an error occurs.

Example

api.unbindService({
  app: 'temp-app',
  service: 'my-db'
}, (err, result) => {});

---

deleteServiceInstance(options, [callback])

Deletes a service instance.

Arguments

• options - An options containing:
  • name - Optional The service instance name. serviceInstanceGuid or name are mandatory but not both.
  • serviceInstanceGuid - Optional The service instance guid. serviceInstanceGuid or name are mandatory but not both.
• callback(err, result) - A callback which is called when function has finished, or an error occurs.

Example

api.deleteServiceInstance({
  app: 'temp-app',
  service: 'my-db'
}, (err, result) => {});