Skip to content

Latest commit

 

History

History
378 lines (289 loc) · 18.1 KB

api.md

File metadata and controls

378 lines (289 loc) · 18.1 KB

Classes

Files

Cloud Files Abstraction

Functions

init([config]) ⇒ Promise.<Files>

Initializes and returns the cloud files SDK.

To use the SDK you must either provide provide your OpenWhisk credentials in credentials.ow or your own Azure blob storage credentials in credentials.azure.

OpenWhisk credentials can also be read from environment variables (__OW_NAMESPACE and __OW_API_KEY).

Typedefs

FilePermissions : Object

Read, Write, Delete permission enum

UrlType : Object

external, internal URL type enum

OpenWhiskCredentials : object

An object holding the OpenWhisk credentials

AzureCredentialsSAS : object

SAS Azure credentials. The sdk needs two SAS credentials to allow access to two already existing containers, a private and a public one (with access=blob).

AzureCredentialsAccount : object

Azure account credentials. Must have the permission to create containers.

RemotePathString : string

a string to the remote path. If the path ends with a / it will be treated as a directory, if not it will be treated as a file.

RemoteFileProperties : object

File properties

FilesLibError : Error
FilesLibErrors : object

Files lib custom errors.

e.sdkDetails provides additional context for each error (e.g. function parameter)

Files

Cloud Files Abstraction

Kind: global abstract class

files.list([filePath]) ⇒ Promise.<Array.<RemoteFileProperties>>

Lists files in a remote folder. If called on a file returns the file info if the file exists. If the file or folder does not exist returns an empty array.

Kind: instance method of Files
Returns: Promise.<Array.<RemoteFileProperties>> - resolves to array of RemoteFileProperties
Access: public

Param Type Description
[filePath] RemotePathString RemotePathString if not specified list all files

files.delete(filePath, [options]) ⇒ Promise.<Array.<string>>

Deletes a remote file or directory

Kind: instance method of Files
Returns: Promise.<Array.<string>> - resolves to array of deleted paths
Access: public

Param Type Default Description
filePath RemotePathString RemotePathString
[options] object {} remoteDeleteOptions
[options.progressCallback] function cb(RemoteFile) is called after the operation completed on each file

files.createReadStream(filePath, [options]) ⇒ Promise.<NodeJS.ReadableStream>

NodeJS only (streams). Does not work on directories.

Creates a read stream

Kind: instance method of Files
Returns: Promise.<NodeJS.ReadableStream> - a readable stream
Access: public

Param Type Default Description
filePath RemotePathString RemotePathString
[options] object {} createReadStreamOptions
[options.position] number read start position of the file. By default is set to 0. If set to bigger than size, throws an ERROR_OUT_OF_RANGE error
[options.length] number number of bytes to read. By default reads everything since starting position. If set to bigger than file size, reads until end.

files.createWriteStream(filePath) ⇒ Promise.<NodeJS.WritableStream>

[UNSTABLE] please prefer using write(<NodeJS.ReadableStream>)

NodeJS only (streams). Does not work on directories.

Returns a write stream. Use stream.on('finish', (bytesWritten) => {}) to listen on completion event

Kind: instance method of Files
Returns: Promise.<NodeJS.WritableStream> - a writable stream
Access: public

Param Type Description
filePath RemotePathString RemotePathString

files.read(filePath, [options]) ⇒ Promise.<Buffer>

Does not work on directories.

Reads a remote file content

Kind: instance method of Files
Returns: Promise.<Buffer> - buffer holding content
Access: public

Param Type Default Description
filePath RemotePathString RemotePathString
[options] object {} remoteReadOptions
[options.position] number read start position of the file. By default is set to 0. If set to bigger than size, throws an ERROR_OUT_OF_RANGE error
[options.length] number number of bytes to read. By default reads everything since starting position. If set to bigger than file size, reads until end.

files.write(filePath, content) ⇒ Promise.<number>

Does not work on directories.

Writes content to a file

Kind: instance method of Files
Returns: Promise.<number> - resolves to number of bytes written
Access: public

Param Type Description
filePath RemotePathString RemotePathString
content string | Buffer | NodeJS.ReadableStream to be written, ReadableStream input works for NodeJS only

files.getProperties(filePath) ⇒ Promise.<RemoteFileProperties>

Reads properties of a file or directory

Kind: instance method of Files
Returns: Promise.<RemoteFileProperties> - resolves RemoteFileProperties

Param Type Description
filePath RemotePathString RemotePathString

files.copy(srcPath, destPath, [options]) ⇒ Promise.<Object.<string, string>>

NodeJS only (streams + fs).

A utility function to copy files and directories across remote and local Files. This is comparable to the scp command

Rules for copy files are:

  1. Remote => Remote
  • a/ (dir) => b/: b/a/
  • a (file) => b/: b/a does nothing if b/a exists and noOverwrite=true
  • a (file) => b : b does nothing if b exists and noOverwrite=true
  • a/ (dir) => b : b/ always allowed: in remote Files we can have both b and b/
  1. Remote => Local
  • a/ => b/: b/a/
  • a => b/: b/a does nothing if b/a exists and noOverwrite=true
  • a => b : b does nothing if b exists and noOverwrite=true
  • a/ => b : b/ throws an error if b exists and is a file: cannot copy a remote dir to a local file
  1. Local => Remote
  • a/ => b/: b/a/
  • a => b/: b/a does nothing if b/a exists and noOverwrite=true
  • a => b : b does nothing if b exists and noOverwrite=true
  • a/ => b: b/ always allowed: in remote Files we can have both b and b/
  1. Local => Local
  • not supported

Kind: instance method of Files
Returns: Promise.<Object.<string, string>> - returns a promise resolving to an object containing all copied files from src to dest { srcFilePath: destFilePath }

Param Type Default Description
srcPath RemotePathString copy source path to a file or directory. If srcPath points to a local file set options.localSrc to true
destPath RemotePathString copy destination path to a file or directory. If destPath points to a local file set options.localDest to true
[options] object {} remoteCopyOptions
[options.localSrc] boolean false Set this option to true to copy files from the local file system. Cannot be combined with localDest.
[options.localDest] boolean false Set this option to true to copy files to the local file system. Cannot be combined with localSrc.
[options.noOverwrite] boolean false set to true to not overwrite existing dest files
[options.progressCallback] function a function that will be called every time the operation completes on a single file,the srcPath and destPath to the copied file are passed as argument to the callback progressCallback(srcPath, destPath)

files.generatePresignURL(filePath, options) ⇒ Promise.<string>

Generate pre-sign URLs for a private file

Kind: instance method of Files
Returns: Promise.<string> - Presign URL for the given file

Param Type Description
filePath RemotePathString RemotePathString
options object Options to generate presign URL
options.expiryInSeconds number presign URL expiry duration
options.permissions string permissions for presigned URL (any combination of rwd)
options.urlType string default 'external', type of URL to return 'internal' or 'external'

files.revokeAllPresignURLs() ⇒ void

Revoke all generated pre-sign URLs

Kind: instance method of Files

init([config]) ⇒ Promise.<Files>

Initializes and returns the cloud files SDK.

To use the SDK you must either provide provide your OpenWhisk credentials in credentials.ow or your own Azure blob storage credentials in credentials.azure.

OpenWhisk credentials can also be read from environment variables (__OW_NAMESPACE and __OW_API_KEY).

Kind: global function
Returns: Promise.<Files> - A Files instance

Param Type Default Description
[config] object {} configuration used to init the sdk
[config.ow] OpenWhiskCredentials OpenWhiskCredentials. Set those if you want to use ootb credentials to access the state management service. OpenWhisk namespace and auth can also be passed through environment variables: __OW_NAMESPACE and __OW_API_KEY
[config.azure] AzureCredentialsAccount | AzureCredentialsSAS bring your own Azure SAS credentials or Azure storage account credentials
[config.tvm] object tvm configuration, applies only when passing OpenWhisk credentials
[config.tvm.apiUrl] string alternative tvm api url.
[config.tvm.cacheFile] string alternative tvm cache file, set to false to disable caching of temporary credentials.

FilePermissions : Object

Read, Write, Delete permission enum

Kind: global typedef

UrlType : Object

external, internal URL type enum

Kind: global typedef

OpenWhiskCredentials : object

An object holding the OpenWhisk credentials

Kind: global typedef
Properties

Name Type Description
namespace string user namespace
auth string auth key

AzureCredentialsSAS : object

SAS Azure credentials. The sdk needs two SAS credentials to allow access to two already existing containers, a private and a public one (with access=blob).

Kind: global typedef
Properties

Name Type Description
sasURLPrivate string sas url to existing private azure blob container
sasURLPublic string sas url to existing public (with access=blob) azure blob container

AzureCredentialsAccount : object

Azure account credentials. Must have the permission to create containers.

Kind: global typedef
Properties

Name Type Description
storageAccount string name of azure storage account
storageAccessKey string access key for azure storage account
containerName string name of container to store files. Another ${containerName}-public will also be used for public files.
[hostName] string custom domain for returned URLs

RemotePathString : string

a string to the remote path. If the path ends with a / it will be treated as a directory, if not it will be treated as a file.

Kind: global typedef

RemoteFileProperties : object

File properties

Kind: global typedef
Properties

Name Type Description
name string unique name of this file, it is the full path
creationTime string utc datetime string when file was created
lastModified string utc datetime string when file last modified
etag string unique ( per modification ) etag for the asset
contentLength number size, in bytes
contentType string mime/type
isDirectory boolean true if file is a directory
isPublic boolean true if file is public
url string remote file URL with URI encoded path, use decodeURIComponent to decode the URL.
internalUrl string remote file URL which allows file access only from Adobe I/O Runtime actions.

FilesLibError : Error

Kind: global typedef

FilesLibErrors : object

Files lib custom errors.

e.sdkDetails provides additional context for each error (e.g. function parameter)

Kind: global typedef
Properties

Name Type Description
ERROR_BAD_ARGUMENT FilesLibError this error is thrown when an argument is missing or has invalid type
ERROR_NOT_IMPLEMENTED FilesLibError this error is thrown when a method is not implemented or when calling methods directly on the abstract class (Files).
ERROR_BAD_CREDENTIALS FilesLibError this error is thrown when the supplied init credentials are invalid.
ERROR_INTERNAL FilesLibError this error is thrown when an unknown error is thrown by the underlying provider or TVM server for credential exchange. More details can be found in e.sdkDetails._internal.
ERROR_FILE_NOT_EXISTS FilesLibError this error is thrown when the filePath does not exists for operations that need the file to exists (e.g. read)
ERROR_BAD_FILE_TYPE FilesLibError this error is thrown when the filePath is not the expected type for operations that need the file to be of a specific type, e.g. write on a dir would fail