@sap/xsenv
Utility for easy setup and access of environment variables and services in Cloud Foundry and XSA.
Applications in Cloud Foundry take various configurations from the environment.
For example Cloud Foundry provides properties of bound services in VCAP_SERVICES environment variable.
To test locally you need to provide these configurations by yourself. This package allows you to provide default configurations in a separate configuration file.
- This reduces clutter by removing configuration data from the app code.
- You don't have to set env vars manually each time you start your app.
- Different developers can use their own configurations for their local tests without changing files under source control. Just add this configuration file to
.gitignore
and .cfignore
.
You can provide default configurations on two levels:
- For Cloud Foundry services via
getServices()
and default-services.json
- For any environment variable via
loadEnv()
and default-env.json
While here we often reference Cloud Foundry, it all applies also to SAP HANA XS Advanced On-premise Runtime which emulates Cloud Foundry as much as possible.
Install
npm install --save @sap/xsenv
Service Lookup
Normally in Cloud Foundry you bind a service instance to your application with a command like this one:
cf bind-service my-app aservice
Here is how you can get this service configuration in your node application:
var xsenv = require('@sap/xsenv');
var services = xsenv.readCFServices();
console.log(services.aservice.credentials);
Often the service instance name is not known in advance. Then you can pass its name as an environment variable and use it like this:
var services = xsenv.readCFServices();
var svc = services[process.env.SERVICE_NAME];
Another alternative is to lookup the service based on its metadata:
var svc = xsenv.cfServiceCredentials({ tag: 'hdb' });
console.log(svc);
This example finds a service binding with hdb
in the tags.
See Service Query below for description of the supported query values.
You can also look up multiple services in a single call:
var xsenv = require('@sap/xsenv');
var services = xsenv.getServices({
hana: { tag: 'hdb' },
scheduler: { label: 'jobs' }
});
var hanaCredentials = services.hana;
var schedulerCredentials = services.scheduler;
This examples finds two services - one with tag hdb
and the other with label jobs
.
getServices
function provides additional convenience that default service configuration can be provided in a JSON file.
To test the above example locally, create a file called default-services.json
in the working directory of your application.
This file should contain something like this:
{
"hana": {
"host": "localhost",
"port": "30015",
"user": "SYSTEM",
"password": "secret"
},
"scheduler": {
"host": "localhost",
"port": "4242",
"user": "my_user",
"password": "secret"
}
}
Notice that the result property names (hana
and scheduler
) are the same as those in the query object and also those in default-services.json
.
Local environment setup describes an alternative approach to provide service configurations for local testing.
User-Provided Service Instances
While this package can look up any kind of bound service instances, you should be aware that User-Provided Service Instances have less properties than managed service instances. Here is an example:
"VCAP_SERVICES": {
"user-provided": [
{
"name": "pubsub",
"label": "user-provided",
"tags": [],
"credentials": {
"binary": "pubsub.rb",
"host": "pubsub01.example.com",
"password": "p@29w0rd",
"port": "1234",
"username": "pubsubuser"
},
"syslog_drain_url": ""
}
]
}
As you can see the only usable property is the name
. In particular, there are no tags for user-provided services.
Service Query
Both getServices
and filterCFServices
use the same service query values.
Query value | Description |
---|
{string} | Matches the service with the same service instance name (name property). Same as { name: '<string>' } . |
{object} | All properties of the given object should match corresponding service instance properties as they appear in VCAP_SERVICES. See below. |
{function} | A function that takes a service object as argument and returns true only if it is considered a match |
If an object is given as a query value, it may have the following properties:
Property | Description |
---|
name | Service instance name - the name you use to bind the service |
label | Service name - the name shown by cf marketplace |
tag | Should match any of the service tags |
plan | Service instance plan - the plan you use in cf create-service |
If multiple properties are given, all of them must match.
Note: Do not confuse the instance name (name
property) with service name (label
property).
Since you can have multiple instances of the same service bound to your app,
instance name is unique while service name is not.
Here ar some examples.
Find service instance by name:
xsenv.cfServiceCredentials('hana');
Look up a service by tag:
xsenv.cfServiceCredentials({ tag: 'relational' });
Match several properties:
xsenv.cfServiceCredentials({ label: 'hana', plan: 'shared' });
Pass a custom filter function:
xsenv.cfServiceCredentials(function(service) {
return /shared/.test(service.plan) && /hdi/.test(service.label);
});
Notice that the filter function is called with the full service object as it appears in VCAP_SERVICES, but cfServiceCredentials
returns only the credentials
property of the matching service.
getServices(query, [servicesFile])
Looks up bound service instances matching the given query.
If a service is not found in VCAP_SERVICES, returns default service configuration loaded from a JSON file.
query
- An object describing requested services. Each property value is a filter as described in Service QueryservicesFile
- (optional) path to JSON file to load default service configuration (default is default-services.json).
If null
, do not load default service configuration.- returns - An object with the same properties as in query argument where the value of each property is the respective service credentials object
- throws - An error, if for some of the requested services no or multiple instances are found
cfServiceCredentials(filter)
Looks up a bound service instance matching the given filter.
Note: this function does not load default service configuration from default-services.json.
filter
- Service lookup criteria as described in Service Query- returns - Credentials object of found service
- throws - An error in case no or multiple matching services are found
filterCFServices(filter)
Returns all bound services that match the given criteria.
filter
- Service lookup criteria as described in Service Query- returns - An array of credentials objects of matching services. Empty array, if no matches found.
readCFServices()
Transforms VCAP_SERVICES to an object where each service instance is mapped to its name.
Given this VCAP_SERVICES example:
{
"hana" : [ {
"credentials" : {
...
},
"label" : "hana",
"name" : "hana1",
"plan" : "shared",
"tags" : [ "hana", "relational" ]
},
{
"credentials" : {
...
},
"label" : "hana",
"name" : "hana2",
"plan" : "shared",
"tags" : [ "hana", "relational", "SP09" ]
} ]
}
readCFServices
would return:
{
hana1: {
"credentials" : {
...
},
"label" : "hana",
"name" : "hana1",
"plan" : "shared",
"tags" : [ "hana", "relational" ]
},
hana2: {
"credentials" : {
...
},
"label" : "hana",
"name" : "hana2",
"plan" : "shared",
"tags" : [ "hana", "relational", "SP09" ]
}
}
Local environment setup
To test your application locally you often need to setup its environment so that resembles the environment in Cloud Foundry.
You can do this easily by defining the necessary environment variables in a JSON file.
For example you can create file default-env.json with the following content in the working directory of the application :
{
"PORT": 3000,
"VCAP_SERVICES": {
"hana": [
{
"credentials": {
"host": "myhana",
"port": "30015",
"user": "SYSTEM",
"password": "secret"
},
"label": "hana",
"name": "hana-R90",
"tags": [
"hana",
"database",
"relational"
]
}
],
"scheduler": [
{
"credentials": {
"host": "localhost",
"port": "4242",
"user": "jobuser",
"password": "jobpassword"
},
"label": "scheduler",
"name": "jobscheduler",
"tags": [
"scheduler"
]
}
]
}
}
Then load it in your application:
xsenv.loadEnv();
console.log(process.env.PORT);
console.log(xsenv.cfServiceCredentials('hana-R90'));
This way you don't need in your code conditional logic if it is running in Clod Foundry or locally.
You can also use a different file name:
xsenv.loadEnv('myenv.json');
loadEnv([file])
Loads the environment from a JSON file.
This function converts each top-level property to a string and sets it in the respective environment variable,
unless it is already set. This function does not change existing environment variables. So the file content acts like default values for environment variables.
This function does not complain if the file does not exist.
file
- optional name of JSON file to load, 'default-env.json'
by default. Does nothing if the file does not exist.
Loading SSL Certificates
If SSL is configured in XSA On-Premise Runtime, it will provide one or more
trusted CA certificates that applications can use to make SSL connections.
If present, the file paths of these certificates are listed in XS_CACERT_PATH
environment variable separated by path.delimiter
(:
on LINUX and ;
on Windows).
loadCertificates([certPath])
Loads the certificates listed in the given path.
If this argument is not provided, it uses XS_CACERT_PATH
environment variable instead.
If that is not set either, the function returns undefined
.
The function returns an array even if a single certificate is provided.
This function is synchronous.
certPath
- optional string with certificate files to load. The file names are separated by path.delimiter
. Default is process.env.XS_CACERT_PATH
.- returns - an array of loaded certificates or
undefined
if certPath
argument is not provided - throws - an error, if some of the files could not be loaded
For example this code loads the trusted CA certificates so they are used for all
subsequent outgoing HTTPS connections:
var https = require('https');
var xsenv = require('@sap/xsenv');
https.globalAgent.options.ca = xsenv.loadCertificates();
This function can be used also to load SSL certificates for HANA like this:
var hdb = require('hdb');
var xsenv = require('@sap/xsenv');
var client = hdb.createClient({
host : 'hostname',
port : 30015,
ca : xsenv.loadCertificates(),
...
});
loadCaCert()
Deprecated. Use loadCertificates
instead.
This function loads the certificates listed in XS_CACERT_PATH
environment variable
into https.globalAgent of Node.js.
All subsequent outgoing HTTPS connections will use these certificates to verify the certificate
of the remote host. The verification should be successful if the certificate of the
remote host is signed (directly or via some intermediary) by some of these trusted
certificates.
It is suggested to call this function once during the application startup.
xsenv.loadCaCert();
If XS_CACERT_PATH
variable is not set, the function does nothing.
This function is synchronous.
It will throw an error if it cannot load some of the certificates.
Debugging
Set DEBUG=xsenv
in the environment to enable debug traces. See debug package for details.