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:

• build cli
• build agent