API Docs for: 0.7.0
Show:

File: lib/util.js

/**
 * Utilities module
 * @module util
 * @namespace util
 * @class __global__
 */
var http = require('http');
var crypto = require('crypto');
var querystring = require('querystring');
var url = require('url');
var settings = require('./settings');


/**
 * Generate path name.
 * Both bucket and object name are optional,
 * but If bucket name not appeared,object name should
 * disappear neither.
 * @method getPathname
 * @param {string} [bucket] bucket name
 * @param {string} [object] object name
 * @return {string} formatted pathname
 */
exports.getPathname = function(bucket,object){
	return bucket ? (object ? '/'+bucket+'/'+querystring.escape(object) : '/'+bucket) : '/';
};

/**
 * Debug mode variable output helper
 * @method debugOutput
 * @param {string} func function name contain the variable
 * @param {string} variable variable name
 * @param {all} variable value
 * @param {string} [sep] seperator for each output
 */
exports.debugOutput = function(func,variable,value,sep){
	if (settings.DEBUG) {
		sep = sep || '==============================';
		console.log(sep);
		console.log(settings.COLORS.BLUE+
			'Function : '+func+
			' ; Variable : '+variable+settings.COLORS.RESET);
		console.log(value);
		console.log(sep);
	}
};

/**
 * Debug mode variable output helper
 * @method debugOutput
 * @param {string} func function name contain the variable
 * @param {string} variable variable name
 * @param {all} variable value
 * @param {string} [sep] seperator for each output
 */
exports.testDebugOutput = function(func,variable,value,sep){
	if (settings.UNITTESTDEBUG) {
		sep = sep || 'xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx';
		console.log(sep);
		console.log(settings.COLORS.BLUE+
			'Function : '+func+
			' ; Variable : '+variable+settings.COLORS.RESET);
		console.log(value);
		console.log(sep);
	}
};

/**
 * Get UTC format timeout millisecond fron now on
 * @method getUTCDate
 * @param {number} timeout millisecond from now on
 * @return {string} UTC format time
 */
exports.getUTCDate = function(timeout){
	timeout = timeout || 0;
	var expire = new Date(Date.now()+timeout)
	return expire.toUTCString();
};

/**
 * Get Unix time from 1970.1.1 to now in seconds
 * @method getUnixTime
 * @param {number} timeout expire timeout millisecond later
 * @return {number} millisecond after unix time to timeout millisecond after
 */
exports.getUnixTime = function(timeout){
	timeout = timeout || 0;
	return Date.now() + timeout;
};

/**
 * 1) 将所有以“x-oss-”为前缀的 HTTP 请求头的名字转换成小写字母。如’X-OSS-Meta-Name: TaoBao’
 * 转换成’x-oss-meta-name: TaoBao’。<br>
 * 2) 将上一步得到的所有 HTTP 请求头按照字典序进行升序排列。<br>
 * 3) 如果有相同名字的请求头,则根据标准 RFC 2616, 4.2 章进行合并(两个值之间只用逗号分隔)。
 * 如有两个名为’x-oss-meta-name’的请求头,对应的值分别为’TaoBao’和’Alipay’,则合并后
 * 为:’x-oss-meta-name:TaoBao,Alipay’。<br>
 * 4) 删除请求头和内容之间分隔符两端出现的任何空格。如’x-oss-meta-name:  TaoBao,Alipay’转换
 * 成:’x-oss-meta-name:TaoBao,Alipay’。<br>
 * 5) 将所有的头和内容用’\n’分隔符分隔拼成最后的 CanonicalizedOSSHeader。
 *
 * @method getCanonicalizedHeader
 * @param {Object} headers http header
 * @return {string} canonicalized header
 */
exports.getCanonicalizedHeader = function(headers){
	var tmpHeaders = {};

	Object.getOwnPropertyNames(headers).forEach(function(key){
		var lower = key.toLowerCase();
		if (lower.indexOf(settings.OSSHeaderPrefix) !== -1) {
			tmpHeaders[lower] = tmpHeaders[lower] === undefined ?
				headers[key] : tmpHeaders[lower] + ',' + headers[key];
		}
	});
	var result = Object.getOwnPropertyNames(tmpHeaders).sort().map(function(key){
		return [key.trim(),tmpHeaders[key].trim()].join(':');
	}).join('\n');

	exports.debugOutput('util.getCanonicalizedHeader','result',result);
	return result;
};

/**
 * 1) 将CanonicalizedResource 置成空字符串(“”)<br>
 * 2) 放入要访问的 OSS 资源:“ /BucketName/ObjectName”(无 ObjectName 则不填)<br>
 * 3) 如果请求的资源包括子资源(sub-resource),那么将所有的子资源按照字典序,从小到大排列并
 * 以’&’为分隔符生成子资源字符串。在 CanonicalizedResource 字符串尾添加“?”和子资源字
 * 符串。此时的 CanonicalizedResource 例子如:/BucketName/ObjectName?acl &uploadId=UploadId<br>
 * 4) 如果用户请求在查询字符串(query string)中指定了要重写(override)返回请求的 header
 * 那么将这些查询字符串及其请求值按照字典序,从小到大排列,以’&’为分隔符,按参数的字典序添加到
 * CanonicalizedResource 中。此时的 CanonicalizedResource 例子:
 * /BucketName/ObjectName?acl&response-content-type=ContentType & uploadId =UploadId
 *
 * @method getCanonicalizedResource
 * @param {Object} queryObj Extra query string in object format
 * @param {string} [bucket] bucket name
 * @param {string} [object] object name
 */
exports.getCanonicalizedResource = function(queryObj,bucket,object){
	bucket = bucket || '';
	object = object || '';

	//check if subresources & overrides defined in settings
	var extra = [];
	Object.getOwnPropertyNames(queryObj).sort().forEach(function(key){
		if (settings.SUBRESOURCES.indexOf(key) !== -1 || settings.OVERRIDES.indexOf(key) !== -1) {
			extra.push( queryObj[key] ? [key,queryObj[key]].join('=') : key );
		}
	});
	extra = extra.sort().join('&');

	var resource = exports.getPathname(bucket,object);
	resource += extra === '' ? '' : '?' + extra;

	exports.debugOutput('util.getCanonicalizedResource','resource',resource);

	return resource;
};

/**
 * Sign message using hmac-sha1
 * @method getSign
 * @param {string} access_key_secret Personal access key secret
 * @param {string} method http method
 * @param {Object} headers http headers
 * @param {Object} queryObj Extra query string in object format
 * @param {string} [bucket] bucket name
 * @param {string} [object] object name
 * @return {string} hmac-sha1 sign message
 */
exports.getSign = function(access_key_secret,method,headers,queryObj,bucket,object){
	content_md5 = headers['Content-MD5'] || '';
	content_type = headers['Content-Type'] || '';
	date = headers['Date'] || exports.getUTCDate(0);
	canonicalizedHeader = exports.getCanonicalizedHeader(headers);
	canonicalizedResource = exports.getCanonicalizedResource(queryObj,bucket,object);

	var stringToSign = [
		method,content_md5,content_type,date,''
	].join('\n');
	stringToSign += canonicalizedHeader ? 
			(canonicalizedResource ? [canonicalizedHeader,canonicalizedResource].join('\n') :canonicalizedHeader) :
			(canonicalizedResource ? canonicalizedResource : '');
	exports.debugOutput('util.getSign','stringToSign',stringToSign);
	var sign = crypto.createHmac(
		'sha1',access_key_secret
	).update(stringToSign).digest('base64');
	return sign;
}

/**
 * Crypto data with MD5
 * @method cryptoMD5
 * @param {string} data Content need crypto
 * @return {string} 128 bit encrypted array encoding with base64
 */
exports.cryptoMD5 = function(data){
	var md5 = crypto.createHash('md5').update(data).digest('base64');
	exports.debugOutput('util.cryptoMD5','md5',md5);
	return md5;
};

/**
 * Authenticated with http header
 * @method _authWithHeader
 * @param {string} method Http method
 * @param {Object} headers Http header
 * @param {Object} queryObj Extra query string in object format
 * @param {Function} callback Function called when get response.
 *   callback supplied with http.Response object
 * @param {string} [bucket] bucket name
 * @param {string} [object] object name
 * @param {string} [data] object content
 */
exports.authWithHeader = function(method,headers,queryObj,callback,bucket,object,data){
	headers['Date'] = headers['Date'] || exports.getUTCDate();
	headers['Content-Length'] = headers['Content-Length'] || 0;
	headers['Authorization'] =
		'OSS '+settings.ACCESS_KEY_ID+':'+
		exports.getSign(
			settings.ACCESS_KEY_SECRET,
			method,headers,queryObj,bucket,object);

	exports.debugOutput('API.authWithHeader','headers',headers);

	var path = url.format({
		'pathname': exports.getPathname(bucket,object),
		'query': queryObj
	});

	http.request({
		'host': settings.HOST,
		'method' : method,
		'path': path,
		'headers': headers,
	},function(response){
		callback(response);
	}).end(data);
};


/**
 * URL 中包含签名示例: 
 * http://storage.aliyun.com/quotes/nelson?OSSAccessKeyId=44CF9590006BF252F707&Expires=1141889120
 * &Signature=vjbyPxybdZaNmGa%2ByT272YEAiv4%3D
 * 在 URL 中实现签名,必须至少包含 Signature,Expires,OSSAccessKeyId
 * 三个参数。Expires 这个参数的值是一个 UNIX 时间(自 UTC 时间 1970 年 1 月 1
 * 号开始的秒数,详见 wiki),用于标识该 URL 的超时时间。如果 OSS 接收到这
 * 个URL请求的时候晚于签名中包含的Expires参数时,则返回请求超时的错误码。
 * 例如:当前时间是 1141889060,开发者希望创建一个 60 秒后自动失效的 URL,13
 * 则可以设置 Expires 时间为 1141889120。
 * 所有的 OSS 支持的请求和各种 Head 参数,在 URL 中进行签名的方法和上
 * 节介绍的签名算法基本一样。主要区别如下:<br>
 * 1) 通过 URL 包含签名时,之前的 Date 参数换成 Expires 参数。<br>
 * 2) 不支持同时在 URL 和 Head 中包含签名。<br>
 * 3) 如果传入的 Signature,Expires,OSSAccessKeyId 出现不止一次,以第一次
 * 为准。<br>
 * 4) 请求先验证请求时间是否晚于 Expires 时间,然后再验证签名。<br>
 *
 * @method authWithUrl
 * @param {object} params variable parameters,the following two are necessary:
 *   <ul>
 *   	<li>method <b>http method</b></li>
 *   	<li>headers <b>http headers</b></li>
 *   </ul>
 *   The following three are optional:
 *   <ul>
 *   	<li>timeout <b>expire millisecond after now</b></li>
 *   	<li>bucket <b>bucket name</b></li>
 *   	<li>object <b>object name</b></li>
 *   </ul>
 * @param {Function} callback Callback function after OSS response,
 *   supplied with http.Response object
 */
exports.authWithUrl = function(params,callback){
	//signature
	var expires = parseInt( exports.getUnixTime(params.timeout||settings.TIMEOUT)/1000 );
	params.headers['Date'] = expires;
	var signature = exports.getSign(
		settings.ACCESS_KEY_SECRET,
		params.method,
		params.headers,
		params.queryObj,
		params.bucket,
		params.object);
	exports.debugOutput('API.authWithUrl','signature',signature);

	//path
	var path = exports.getPathname(params.bucket,params.object) + '?' +
		'OSSAccessKeyId=' + settings.ACCESS_KEY_ID +
		'&Expires=' + expires +
		'&Signature=' + querystring.escape(signature);
	params.headers['Date'] = exports.getUTCDate();
	var extra = querystring.stringify(params.headers);
	path += extra === '' ? '' : '&' + extra;
	exports.debugOutput('API.authWithUrl','path',path);

	http.request({
		'host': settings.HOST,
		'method': params.method,
		'path': path,
	},function(response){
		callback(response);
	}).end();
};