@liara/sdk v0.2.2

Liara JavaScript SDK

Initialize Liara Client object.

var Liara = require('@liara/sdk');

var liaraClient = new Liara.Storage.Client({
    accessKey: 'Q3AM3UQ867SPQQA43P2F',
    secretKey: 'zuf+tfteSlswRu7BJ86wekitnifILbZam1KYY3TG',
    endPoint: '2aoassadfu234.storage.liara.ir',
});

1. Constructor

new Liara.Storage.Client ({endPoint, accessKey, secretKey})

Parameters

Example

Create client for Minio

var Liara = require('@liara/sdk');

var liaraClient = new Liara.Storage.Client({
    accessKey: 'Q3AM3UQ867SPQQA43P2F',
    secretKey: 'zuf+tfteSlswRu7BJ86wekitnifILbZam1KYY3TG',
    endPoint: '2aoassadfu234.storage.liara.ir',
});

2. Bucket operations

makeBucket(bucketName, callback)

Creates a new bucket.

Parameters

Example

liaraClient.makeBucket('mybucket', function(err) {
  if (err) return console.log('Error creating bucket.', err)
  console.log('Bucket created successfully.')
})

listBuckets(callback)

Lists all buckets.

Parameters

bucketStream emits Object with the format:-

Example

liaraClient.listBuckets(function(err, buckets) {
  if (err) return console.log(err)
  console.log('buckets :', buckets)
})

bucketExists(bucketName, callback)

Checks if a bucket exists.

Parameters

Example

liaraClient.bucketExists('mybucket', function(err, exists) {
  if (err) {
    return console.log(err)
  }
  if (exists) {
    return console.log('Bucket exists.')
  }
})

removeBucket(bucketName, callback)

Removes a bucket.

Parameters

Example

liaraClient.removeBucket('mybucket', function(err) {
  if (err) return console.log('unable to remove bucket.')
  console.log('Bucket removed successfully.')
})

listObjects(bucketName, prefix, recursive)

Lists all objects in a bucket.

Parameters

Return Value

The object is of the format:

Example

var stream = liaraClient.listObjects('mybucket','', true)
stream.on('data', function(obj) { console.log(obj) } )
stream.on('error', function(err) { console.log(err) } )

listObjectsV2(bucketName, prefix, recursive, startAfter)

Lists all objects in a bucket using S3 listing objects V2 API

Parameters

Return Value

The object is of the format:

Example

var stream = liaraClient.listObjectsV2('mybucket','', true,'')
stream.on('data', function(obj) { console.log(obj) } )
stream.on('error', function(err) { console.log(err) } )

listIncompleteUploads(bucketName, prefix, recursive)

Lists partially uploaded objects in a bucket.

Parameters

Return Value

Example

var Stream = liaraClient.listIncompleteUploads('mybucket', '', true)
Stream.on('data', function(obj) {
  console.log(obj)
})
Stream.on('end', function() {
  console.log('End')
})
Stream.on('error', function(err) {
  console.log(err)
})

3. Object operations

getObject(bucketName, objectName, callback)

Downloads an object as a stream.

Parameters

Example

var size = 0
liaraClient.getObject('mybucket', 'photo.jpg', function(err, dataStream) {
  if (err) {
    return console.log(err)
  }
  dataStream.on('data', function(chunk) {
    size += chunk.length
  })
  dataStream.on('end', function() {
    console.log('End. Total size = ' + size)
  })
  dataStream.on('error', function(err) {
    console.log(err)
  })
})

getPartialObject(bucketName, objectName, offset, length, callback)

Downloads the specified range bytes of an object as a stream.

Parameters

Example

var size = 0
// reads 30 bytes from the offset 10.
liaraClient.getPartialObject('mybucket', 'photo.jpg', 10, 30, function(err, dataStream) {
  if (err) {
    return console.log(err)
  }
  dataStream.on('data', function(chunk) {
    size += chunk.length
  })
  dataStream.on('end', function() {
    console.log('End. Total size = ' + size)
  })
  dataStream.on('error', function(err) {
    console.log(err)
  })
})

fGetObject(bucketName, objectName, filePath, callback)

Downloads and saves the object as a file in the local filesystem.

Parameters

Example

var size = 0
liaraClient.fGetObject('mybucket', 'photo.jpg', '/tmp/photo.jpg', function(err) {
  if (err) {
    return console.log(err)
  }
  console.log('success')
})

putObject(bucketName, objectName, stream, size, metaData, callback)

Uploads an object from a stream/Buffer.

From a stream

Parameters

Example

The maximum size of a single object is limited to 5TB. putObject transparently uploads objects larger than 5MiB in multiple parts. This allows failed uploads to resume safely by only uploading the missing parts. Uploaded data is carefully verified using MD5SUM signatures.

var Fs = require('fs')
var file = '/tmp/40mbfile'
var fileStream = Fs.createReadStream(file)
var fileStat = Fs.stat(file, function(err, stats) {
  if (err) {
    return console.log(err)
  }
  liaraClient.putObject('mybucket', '40mbfile', fileStream, stats.size, function(err, etag) {
    return console.log(err, etag) // err should be null
  })
})

From a "Buffer" or a "string"

Parameters

Example

var buffer = 'Hello World'
liaraClient.putObject('mybucket', 'hello-file', buffer, function(err, etag) {
  return console.log(err, etag) // err should be null
})

fPutObject(bucketName, objectName, filePath, metaData, callback)

Uploads contents from a file to objectName.

Parameters

Example

The maximum size of a single object is limited to 5TB. fPutObject transparently uploads objects larger than 5MiB in multiple parts. This allows failed uploads to resume safely by only uploading the missing parts. Uploaded data is carefully verified using MD5SUM signatures.

var file = '/tmp/40mbfile'
var metaData = {
  'Content-Type': 'text/html',
  'Content-Language': 123,
  'X-Amz-Meta-Testing': 1234,
  'example': 5678
}
liaraClient.fPutObject('mybucket', '40mbfile', file, metaData, function(err, etag) {
  return console.log(err, etag) // err should be null
})

copyObject(bucketName, objectName, sourceObject, conditions, callback)

Copy a source object into a new object in the specified bucket.

Parameters

Example

var conds = new Minio.CopyConditions()
conds.setMatchETag('bd891862ea3e22c93ed53a098218791d')
liaraClient.copyObject('mybucket', 'newobject', '/mybucket/srcobject', conds, function(e, data) {
  if (e) {
    return console.log(e)
  }
  console.log("Successfully copied the object:")
  console.log("etag = " + data.etag + ", lastModified = " + data.lastModified)
})

statObject(bucketName, objectName, callback)

Gets metadata of an object.

Parameters

Example

liaraClient.statObject('mybucket', 'photo.jpg', function(err, stat) {
  if (err) {
    return console.log(err)
  }
  console.log(stat)
})

removeObject(bucketName, objectName, callback)

Removes an object.

Parameters

Example

liaraClient.removeObject('mybucket', 'photo.jpg', function(err) {
  if (err) {
    return console.log('Unable to remove object', err)
  }
  console.log('Removed the object')
})

removeObjects(bucketName, objectsList, callback)

Remove all objects in the objectsList.

Parameters

Example

var objectsList = []

// List all object paths in bucket my-bucketname.
var objectsStream = s3Client.listObjects('my-bucketname', 'my-prefixname', true)

objectsStream.on('data', function(obj) {
  objectsList.push(obj.name);
})

objectsStream.on('error', function(e) {
  console.log(e);
})

objectsStream.on('end', function() {

  s3Client.removeObjects('my-bucketname',objectsList, function(e) {
    if (e) {
        return console.log('Unable to remove Objects ',e)
    }
    console.log('Removed the objects successfully')
  })

})

removeIncompleteUpload(bucketName, objectName, callback)

Removes a partially uploaded object.

Parameters

Example

liaraClient.removeIncompleteUpload('mybucket', 'photo.jpg', function(err) {
  if (err) {
    return console.log('Unable to remove incomplete object', err)
  }
  console.log('Incomplete object removed successfully.')
})

4. Presigned operations

Presigned URLs are generated for temporary download/upload access to private objects.

presignedUrl(httpMethod, bucketName, objectName, expiry, reqParams, requestDate, cb)

Generates a presigned URL for the provided HTTP method, 'httpMethod'. Browsers/Mobile clients may point to this URL to directly download objects even if the bucket is private. This presigned URL can have an associated expiration time in seconds after which the URL is no longer valid. The default value is 7 days.

Parameters

Example 1

// presigned url for 'getObject' method.
// expires in a day.
liaraClient.presignedUrl('GET', 'mybucket', 'hello.txt', 24*60*60, function(err, presignedUrl) {
  if (err) return console.log(err)
  console.log(presignedUrl)
})

Example 2

// presigned url for 'listObject' method.
// Lists objects in 'myBucket' with prefix 'data'.
// Lists max 1000 of them.
liaraClient.presignedUrl('GET', 'mybucket', '', 1000, {'prefix': 'data', 'max-keys': 1000}, function(err, presignedUrl) {
  if (err) return console.log(err)
  console.log(presignedUrl)
})

presignedGetObject(bucketName, objectName, expiry, respHeaders, requestDate, cb)

Generates a presigned URL for HTTP GET operations. Browsers/Mobile clients may point to this URL to directly download objects even if the bucket is private. This presigned URL can have an associated expiration time in seconds after which the URL is no longer valid. The default value is 7 days.

Parameters

Example

// expires in a day.
liaraClient.presignedGetObject('mybucket', 'hello.txt', 24*60*60, function(err, presignedUrl) {
  if (err) return console.log(err)
  console.log(presignedUrl)
})

presignedPutObject(bucketName, objectName, expiry, callback)

Generates a presigned URL for HTTP PUT operations. Browsers/Mobile clients may point to this URL to upload objects directly to a bucket even if it is private. This presigned URL can have an associated expiration time in seconds after which the URL is no longer valid. The default value is 7 days.

Parameters

Example

// expires in a day.
liaraClient.presignedPutObject('mybucket', 'hello.txt', 24*60*60, function(err, presignedUrl) {
  if (err) return console.log(err)
  console.log(presignedUrl)
})

presignedPostPolicy(policy, callback)

Allows setting policy conditions to a presigned URL for POST operations. Policies such as bucket name to receive object uploads, key name prefixes, expiry policy may be set.

Parameters

Create policy:

var policy = liaraClient.newPostPolicy()

Apply upload policy restrictions:

// Policy restricted only for bucket 'mybucket'.
policy.setBucket('mybucket')

// Policy restricted only for hello.txt object.
policy.setKey('hello.txt')

or

// Policy restricted for incoming objects with keyPrefix.
policy.setKeyStartsWith('keyPrefix')

var expires = new Date
expires.setSeconds(24 * 60 * 60 * 10)
// Policy expires in 10 days.
policy.setExpires(expires)

// Only allow 'text'.
policy.setContentType('text/plain')

// Only allow content size in range 1KB to 1MB.
policy.setContentLengthRange(1024, 1024*1024)

POST your content from the browser using superagent:

liaraClient.presignedPostPolicy(policy, function(err, data) {
  if (err) return console.log(err)

  var req = superagent.post(data.postURL)
  _.each(data.formData, function(value, key) {
    req.field(key, value)
  })

  // file contents.
  req.attach('file', '/path/to/hello.txt', 'hello.txt')

  req.end(function(err, res) {
    if (err) {
      return console.log(err.toString())
    }
    console.log('Upload successful.')
  })
})

5. Bucket Policy & Notification operations

Buckets are configured to trigger notifications on specified types of events and paths filters.

getBucketNotification(bucketName, cb)

Fetch the notification configuration stored in the S3 provider and that belongs to the specified bucket name.

Parameters

Example

liaraClient.getBucketNotification('mybucket', function(err, bucketNotificationConfig) {
  if (err) return console.log(err)
  console.log(bucketNotificationConfig)
})

setBucketNotification(bucketName, bucketNotificationConfig, callback)

Upload a user-created notification configuration and associate it to the specified bucket name.

Parameters

Example

// Create a new notification object
var bucketNotification = new Minio.NotificationConfig();

// Setup a new topic configuration
var arn = Minio.buildARN('aws', 'sns', 'us-west-2', '408065449417', 'TestTopic')
var topic = new Minio.TopicConfig(arn)
topic.addFilterSuffix('.jpg')
topic.addFilterPrefix('myphotos/')
topic.addEvent(Minio.ObjectReducedRedundancyLostObject)
topic.addEvent(Minio.ObjectCreatedAll)

// Add the topic to the overall notification object
bucketNotification.add(topic)

liaraClient.setBucketNotification('mybucket', bucketNotification, function(err) {
  if (err) return console.log(err)
  console.log('Success')
})

removeAllBucketNotification(bucketName, callback)

Remove the bucket notification configuration associated to the specified bucket.

Parameters

liaraClient.removeAllBucketNotification('my-bucketname', function(e) {
  if (e) {
    return console.log(e)
  }
  console.log("True")
})

listenBucketNotification(bucketName, prefix, suffix, events)

Listen for notifications on a bucket. Additionally one can provider filters for prefix, suffix and events. There is no prior set bucket notification needed to use this API. This is an Minio extension API where unique identifiers are regitered and unregistered by the server automatically based on incoming requests.

Returns an EventEmitter, which will emit a notification event carrying the record.

To stop listening, call .stop() on the returned EventEmitter.

Parameters

See here for a full example.

var listener = liaraClient.listenBucketNotification('my-bucketname', 'photos/', '.jpg', ['s3:ObjectCreated:*'])
listener.on('notification', function(record) {
  // For example: 's3:ObjectCreated:Put event occurred (2016-08-23T18:26:07.214Z)'
  console.log('%s event occurred (%s)', record.eventName, record.eventTime)
  listener.stop()
})

getBucketPolicy(bucketName , callback)

Get the bucket policy associated with the specified bucket. If objectPrefix is not empty, the bucket policy will be filtered based on object permissions as well.

Parameters

// Retrieve bucket policy of 'my-bucketname'
liaraClient.getBucketPolicy('my-bucketname', function(err, policy) {
  if (err) throw err

  console.log(`Bucket policy file: ${policy}`)
})

setBucketPolicy(bucketName, bucketPolicy, callback)

Set the bucket policy on the specified bucket. bucketPolicy is detailed here.

Parameters

// Set the bucket policy of `my-bucketname`
liaraClient.setBucketPolicy('my-bucketname', JSON.stringify(policy), function(err) {
  if (err) throw err

  console.log('Bucket policy set')
})

6. HTTP request options

setRequestOptions(options)

Set the HTTP/HTTPS request options. Supported options are agent (http.Agent()) and tls related options ('agent', 'ca', 'cert', 'ciphers', 'clientCertEngine', 'crl', 'dhparam', 'ecdhCurve', 'honorCipherOrder', 'key', 'passphrase', 'pfx', 'rejectUnauthorized', 'secureOptions', 'secureProtocol', 'servername', 'sessionIdContext') documented here

// Do not reject self signed certificates.
liaraClient.setRequestOptions({rejectUnauthorized: false})

License

MIT © Liara