README
nonstop-index-client
Library for communicating with the nonstop index HTTP API.
Built around hypermedia with hyped and halon.
Use
To get a configured instance of the server API, you can use one of the following approaches:
Configuration hash
See the Configuration section for a detailed explanation of the possible configuration values
// for uploading
var server = require( 'nonstop-index-client' )( {
index: {
host: 'my-index',
port: 443,
ssl: true
}
} );
// for getting package lists/downloading
var server = require( 'nonstop-index-client' )( {
index: {
host: 'my-index',
port: 443,
ssl: true
},
package: {
project: 'test',
owner: 'arobson',
branch: 'master'
}
} );
// package lists will use the following URL (note - architecture and platform are set automatically)
// https://my-index:443/api/package/list?project=test&owner=arobson&branch=master&platform=darwin&architecture=x64
Daedalus - Service and Configuration
This example is a bit over-simplified. See daedalus for more advanced use patterns. The point is to show how you can easily use this library in conjunction with daedalus and fount to auto-discover the nonstop-index end point from Consul.
index.js
var daedalus = require( 'daedalus' )();
var server;
daedalus.initialize( {
index: {
service: 'conitnua-index',
module: './index-client.js',
config: 'index-client'
}
} )
.then( function( fount ) {
fount.resolve( 'index', function( index ) { server = index; } );
} );
index-client.js
// the format of the function returned from the module matches
// what daedalus expects
module.exports = require( 'nonstop-index-client' );
Configuration
The configuration hash can contain a lot of information. Depending on your use case, the required minimum information changes to ensure proper function. Defaults are shown for most values except where noted.
{
index: {
host: 'localhost',
api: '/api',
packages: '/nonstop/package', // URL segment where packages available for download are located
port: 12321,
ssl: false,
token: '' // API token used to connect to the index
},
package: {
architecture: , // defaults to your system's architecture, x86 or x64
branch: undefined,
build: undefined,
downloads: './downloads', // where to download packages
owner: undefined,
platform: sysInfo.platform, // defaults to the platform of your OS: 'win32', 'linux' or 'darwin'
project: undefined,
releaseOnly: false, // indicates you only want to see releases when requesting the latest
version: undefined
}
}
Because this library uses configya, you can provide environment variables to override any of the values above. Here is a list for convenience:
- NONSTOP_INDEX_HOST
- NONSTOP_INDEX_API
- NONSTOP_INDEX_PACKAGES
- NONSTOP_INDEX_PORT
- NONSTOP_INDEX_SSL
- NONSTOP_INDEX_TOKEN
- NONSTOP_PACKAGE_ARCHITECTURE
- NONSTOP_PACKAGE_BRANCH
- NONSTOP_PACKAGE_BUILD
- NONSTOP_PACKAGE_FILES
- NONSTOP_PACKAGE_OWNER
- NONSTOP_PACKAGE_PLATFORM
- NONSTOP_PACKAGE_PROJECT
- NONSTOP_PACKAGE_RELEASE
- NONSTOP_PACKAGE_VERSION
Note: if you will be requesting package lists, you must provide project, owner and branch in the config. There are no defaults for these values.
Uploading Packages (cli/build agent)
The only required information can be provided via the service argument from daedalus or via the config argument.
var index = require( 'nonstop-index-client' )( { host: 'my-index', port: 80 } );
Listing and Downloading Packages (bootstrapper)
Listing and downloading require the project, owner and branch to be specified (at least). The platform and architecture are automatically populated based on the machine the code is running on.
var server = require( 'nonstop-index-client' )( {
index: {
host: 'my-index',
port: 80,
project: 'test',
owner: 'arobson',
branch: 'master',
token: 'yourAPIToken'
}
} );
Server API
Once you have access to the server instance, you can find the latest package version available, download a package or upload a package.
Changing the package filter
The parameters you set during configuration which change what packages will be "available" when getting latest can be changed during runtime by accessing the filter. The filter exposes a chainable set of calls for each of the parameters.
// changing the owner and branch of the package
index.config.filter.owner( 'mainRepo' ).branch( 'production' );
These changes will take affect the very next time getLatest
is called.
download( package )
Downloads the target package. The file will be downloaded to the path specified by the downloads
property of the config hash (default is './downloads'). Returns a promise that resolves to an object with the format:
{
path: /* path where the file was downloaded */,
installPath: /* path where packages should be unpacked */,
file: /* the file that was downloaded */
}
// target - the full package name to download
index.download( 'test~arobson~master~0.1.0~1~darwin~any~any~x64.tar.gz' )
.then( function( info ) {
// on success
} );
getLatest( ignore )
Gets information for the latest available package given the package properties set by config (or by the set calls). Returns a promise that resolves to a package information object with the format:
{
file: 'proj1~owner1~branch2~0.1.0~1~darwin~OSX~10.9.2~x64.tar.gz'
project: 'test',
owner: 'arobson',
branch: 'master',
version: '0.1.0-1',
build: '1',
platform: 'darwin',
osName: 'any',
osVersion: 'any',
architecture: 'x64'
}
Most likely, the property you need from this object will be the file
property - supplying this to the download
call will allow your application to download the latest package matching the configured filter.
// ignore - an array of versions that should be ignored when determining the latest package
index.getLatest( [] )
.then( function( latest ) {
index.download( latest.file )
.then( function( info ) {
...
} )
} );
upload( file )
Uploads a package. Returns a promise that resolves to the package information on success (statusCode === 200).
index.upload( './path/proj1~owner1~branch2~0.1.0~1~darwin~OSX~10.9.2~x64.tar.gz' )
.then( function( packageInfo ) {
// on success
} );
Dependencies
This would not have been possible without several great Node modules:
- configya
- debug
- fount
- halon
- lodash
- machina
- mkdirp
- nonstop-pack
- request
- when
Dependents
The following nonstop projects rely on this library: