From da199027d2458cd03eeab87f12d5b0f03b80f9a4 Mon Sep 17 00:00:00 2001 From: Daryl White <53910321+djwfyi@users.noreply.github.com> Date: Wed, 24 Aug 2022 16:33:13 -0500 Subject: [PATCH] Adding checklist items for hardware, software, and security (#525) This adds content to the three stub files. Corrects the Makefile for incorrect importing of Javascript docs into the Haskell folder. Corrects community Slack URLs to point to slack.min.io. --- Makefile | 14 +- ...-side-replication-resynchronize-remote.rst | 2 +- source/developers/haskell/API.md | 2975 +++++------------ source/developers/haskell/quickstart.md | 377 +-- source/developers/javascript/API.md | 2971 +++++++++++----- source/developers/javascript/quickstart.md | 377 ++- source/operations/checklists.rst | 2 +- source/operations/checklists/hardware.rst | 247 +- source/operations/checklists/security.rst | 83 +- source/operations/checklists/software.rst | 69 +- source/operations/data-recovery.rst | 2 +- .../decommission-server-pool.rst | 2 +- source/operations/troubleshooting.rst | 2 +- .../minio-mc-admin/mc-admin-decommission.rst | 2 +- 14 files changed, 3759 insertions(+), 3366 deletions(-) diff --git a/Makefile b/Makefile index e9e34608..85cce7c8 100644 --- a/Makefile +++ b/Makefile @@ -43,8 +43,8 @@ else @make sync-kes-version @make sync-sdks endif - @$(SPHINXBUILD) -M html "$(SOURCEDIR)" "$(BUILDDIR)/$(GITDIR)/$@" $(SPHINXOPTS) $(O) -t $@ @npm run build + @$(SPHINXBUILD) -M html "$(SOURCEDIR)" "$(BUILDDIR)/$(GITDIR)/$@" $(SPHINXOPTS) $(O) -t $@ windows: ifeq ($(BUILD_DEPENDENCIES),FALSE) @@ -55,8 +55,8 @@ else @make sync-kes-version @make sync-sdks endif - @$(SPHINXBUILD) -M html "$(SOURCEDIR)" "$(BUILDDIR)/$(GITDIR)/$@" $(SPHINXOPTS) $(O) -t $@ @npm run build + @$(SPHINXBUILD) -M html "$(SOURCEDIR)" "$(BUILDDIR)/$(GITDIR)/$@" $(SPHINXOPTS) $(O) -t $@ macos: ifeq ($(BUILD_DEPENDENCIES),FALSE) @@ -67,8 +67,8 @@ else @make sync-kes-version @make sync-sdks endif - @$(SPHINXBUILD) -M html "$(SOURCEDIR)" "$(BUILDDIR)/$(GITDIR)/$@" $(SPHINXOPTS) $(O) -t $@ @npm run build + @$(SPHINXBUILD) -M html "$(SOURCEDIR)" "$(BUILDDIR)/$(GITDIR)/$@" $(SPHINXOPTS) $(O) -t $@ k8s: ifeq ($(BUILD_DEPENDENCIES),FALSE) @@ -80,8 +80,8 @@ else @make sync-kes-version @make sync-sdks endif - @$(SPHINXBUILD) -M html "$(SOURCEDIR)" "$(BUILDDIR)/$(GITDIR)/$@" $(SPHINXOPTS) $(O) -t $@ @npm run build + @$(SPHINXBUILD) -M html "$(SOURCEDIR)" "$(BUILDDIR)/$(GITDIR)/$@" $(SPHINXOPTS) $(O) -t $@ container: ifeq ($(BUILD_DEPENDENCIES),FALSE) @@ -92,8 +92,8 @@ else @make sync-kes-version @make sync-sdks endif - @$(SPHINXBUILD) -M html "$(SOURCEDIR)" "$(BUILDDIR)/$(GITDIR)/$@" $(SPHINXOPTS) $(O) -t $@ @npm run build + @$(SPHINXBUILD) -M html "$(SOURCEDIR)" "$(BUILDDIR)/$(GITDIR)/$@" $(SPHINXOPTS) $(O) -t $@ sync-operator-version: @echo "Retrieving latest Operator version" @@ -250,8 +250,8 @@ sync-javascript-docs: @echo "Retrieving JavaScript docs from github.com/minio/minio-js" @$(eval JAVASCRIPTLATEST = $(shell wget -q https://api.github.com/repos/minio/minio-js/releases/latest -O - | jq -r '.tag_name')) @echo "Latest stable is ${JAVASCRIPTLATEST}" - $(shell wget -q -O source/developers/haskell/API.md https://raw.githubusercontent.com/minio/minio-js/${JAVASCRIPTLATEST}/docs/API.md) - $(shell wget -q -O source/developers/haskell/quickstart.md https://raw.githubusercontent.com/minio/minio-js/${JAVASCRIPTLATEST}/README.md) + $(shell wget -q -O source/developers/javascript/API.md https://raw.githubusercontent.com/minio/minio-js/${JAVASCRIPTLATEST}/docs/API.md) + $(shell wget -q -O source/developers/javascript/quickstart.md https://raw.githubusercontent.com/minio/minio-js/${JAVASCRIPTLATEST}/README.md) @$(eval kname = $(shell uname -s)) diff --git a/source/administration/bucket-replication/server-side-replication-resynchronize-remote.rst b/source/administration/bucket-replication/server-side-replication-resynchronize-remote.rst index 5ac6295e..afa45017 100644 --- a/source/administration/bucket-replication/server-side-replication-resynchronize-remote.rst +++ b/source/administration/bucket-replication/server-side-replication-resynchronize-remote.rst @@ -29,7 +29,7 @@ Resynchronization is a per-bucket process. You must repeat resynchronization for `MinIO SUBNET `__ users can `log in `__ and create a new issue related to resynchronization. Coordination with MinIO Engineering via SUBNET can ensure successful resynchronization and restoration of normal operations, including performance testing and health diagnostics. - Community users can seek support on the `MinIO Community Slack `__. Community Support is best-effort only and has no SLAs around responsiveness. + Community users can seek support on the `MinIO Community Slack `__. Community Support is best-effort only and has no SLAs around responsiveness. .. _minio-bucket-replication-serverside-resynchronize-requirements: diff --git a/source/developers/haskell/API.md b/source/developers/haskell/API.md index d64ed38f..d90d60ca 100644 --- a/source/developers/haskell/API.md +++ b/source/developers/haskell/API.md @@ -1,2149 +1,1030 @@ -# JavaScript Client API Reference [![Slack](https://slack.min.io/slack?type=svg)](https://slack.min.io) +# MinIO Haskell SDK API Reference ## Initialize MinIO Client object. -## MinIO +### MinIO - for public Play server -```js -var Minio = require('minio') +```haskell +minioPlayCI :: ConnectInfo +minioPlayCI -var minioClient = new Minio.Client({ - endPoint: 'play.min.io', - port: 9000, - useSSL: true, - accessKey: 'Q3AM3UQ867SPQQA43P2F', - secretKey: 'zuf+tfteSlswRu7BJ86wekitnifILbZam1KYY3TG' -}); ``` -## AWS S3 +### AWS S3 -```js -var Minio = require('minio') +```haskell +awsCI :: ConnectInfo +awsCI { connectAccesskey = "your-access-key" + , connectSecretkey = "your-secret-key" + } -var s3Client = new Minio.Client({ - endPoint: 's3.amazonaws.com', - accessKey: 'YOUR-ACCESSKEYID', - secretKey: 'YOUR-SECRETACCESSKEY' -}) ``` -| Bucket operations | Object operations | Presigned operations | Bucket Policy & Notification operations | Custom Settings | | -|-------------------------------------------------------|-----------------------------------------------------|-----------------------------------------------|---------------------------------------------------------------|-------------------------------------------------------|-----| -| [`makeBucket`](#makeBucket) | [`getObject`](#getObject) | [`presignedUrl`](#presignedUrl) | [`getBucketNotification`](#getBucketNotification) | [`setS3TransferAccelerate`](#setS3TransferAccelerate) | | -| [`listBuckets`](#listBuckets) | [`getPartialObject`](#getPartialObject) | [`presignedGetObject`](#presignedGetObject) | [`setBucketNotification`](#setBucketNotification) | | | -| [`bucketExists`](#bucketExists) | [`fGetObject`](#fGetObject) | [`presignedPutObject`](#presignedPutObject) | [`removeAllBucketNotification`](#removeAllBucketNotification) | | | -| [`removeBucket`](#removeBucket) | [`putObject`](#putObject) | [`presignedPostPolicy`](#presignedPostPolicy) | [`getBucketPolicy`](#getBucketPolicy) | | | -| [`listObjects`](#listObjects) | [`fPutObject`](#fPutObject) | | [`setBucketPolicy`](#setBucketPolicy) | | | -| [`listObjectsV2`](#listObjectsV2) | [`copyObject`](#copyObject) | | [`listenBucketNotification`](#listenBucketNotification) | | | -| [`listIncompleteUploads`](#listIncompleteUploads) | [`statObject`](#statObject) | | | | | -| [`getBucketVersioning`](#getBucketVersioning) | [`removeObject`](#removeObject) | | | | | -| [`setBucketVersioning`](#setBucketVersioning) | [`removeObjects`](#removeObjects) | | | | | -| [`getBucketTagging`](#getBucketTagging) | [`removeIncompleteUpload`](#removeIncompleteUpload) | | | | | -| [`setBucketTagging`](#setBucketTagging) | [`putObjectRetention`](#putObjectRetention) | | | | | -| [`removeBucketTagging`](#removeBucketTagging) | [`getObjectRetention`](#getObjectRetention) | | | | | -| [`setBucketLifecycle`](#setBucketLifecycle) | [`putObjectTagging`](#putObjectTagging) | | | | | -| [`getBucketLifecycle`](#getBucketLifecycle) | [`removeObjectTagging`](#removeObjectTagging) | | | | | -| [`removeBucketLifecycle`](#removeBucketLifecycle) | [`getObjectTagging`](#getObjectTagging) | | | | | -| [`setObjectLockConfig`](#setObjectLockConfig) | [`getObjectLegalHold`](#getObjectLegalHold) | | | | | -| [`getObjectLockConfig`](#getObjectLockConfig) | [`setObjectLegalHold`](#setObjectLegalHold) | | | | | -| [`getBucketEncryption`](#getBucketEncryption) | [`composeObject`](#composeObject) | | | | | -| [`setBucketEncryption`](#setBucketEncryption) | [`selectObjectContent`](#selectObjectContent) | | | | | -| [`removeBucketEncryption`](#removeBucketEncryption) | | | | | | -| [`setBucketReplication`](#setBucketReplication) | | | | | | -| [`getBucketReplication`](#getBucketReplication) | | | | | | -| [`removeBucketReplication`](#removeBucketReplication) | | | | | | -## 1. Constructor +| Bucket operations | Object Operations | Presigned Operations | +|:--------------------------------------------------|:----------------------------------------------|:--------------------------------------------------| +| [`listBuckets`](#listBuckets) | [`getObject`](#getObject) | [`presignedGetObjectUrl`](#presignedGetObjectUrl) | +| [`makeBucket`](#makeBucket) | [`putObject`](#putObject) | [`presignedPutObjectUrl`](#presignedPutObjectUrl) | +| [`removeBucket`](#removeBucket) | [`fGetObject`](#fGetObject) | [`presignedPostPolicy`](#presignedPostPolicy) | +| [`listObjects`](#listObjects) | [`fPutObject`](#fPutObject) | | +| [`listObjectsV1`](#listObjectsV1) | [`copyObject`](#copyObject) | | +| [`listIncompleteUploads`](#listIncompleteUploads) | [`removeObject`](#removeObject) | | +| [`bucketExists`](#bucketExists) | [`selectObjectContent`](#selectObjectContent) | | - -### new Minio.Client ({endPoint, port, useSSL, accessKey, secretKey, region, transport, sessionToken, partSize}) +## 1. Connecting and running operations on the storage service -| | -| ---- | -|``new Minio.Client ({endPoint, port, useSSL, accessKey, secretKey, region, transport, sessionToken, partSize})``| -|Initializes a new client object.| +The Haskell MinIO SDK provides high-level functionality to perform +operations on a MinIO server or any AWS S3-like API compatible storage +service. -__Parameters__ +### The `ConnectInfo` type -| Param | Type | Description | -|----------------|----------|--------------------------------------------------------------------------------------------------------------| -| `endPoint` | _string_ | endPoint is a host name or an IP address. | -| `port` | _number_ | TCP/IP port number. This input is optional. Default value set to 80 for HTTP and 443 for HTTPs. | -| `useSSL` | _bool_ | If set to true, https is used instead of http. Default is true. | -| `accessKey` | _string_ | accessKey is like user-id that uniquely identifies your account. | -| `secretKey` | _string_ | secretKey is the password to your account. | -| `sessionToken` | _string_ | Set this value to provide x-amz-security-token (AWS S3 specific). (Optional) | -| `region` | _string_ | Set this value to override region cache. (Optional) | -| `transport` | _string_ | Set this value to pass in a custom transport. (Optional) | -| `partSize` | _number_ | Set this value to override default part size of 64MB for multipart uploads. (Optional) | -| `pathStyle` | _bool_ | Set this value to override default access behavior (path) for non AWS endpoints. Default is true. (Optional) | +The `ConnectInfo` record-type contains connection information for a +particular server. It is recommended to construct the `ConnectInfo` +value using one of the several smart constructors provided by the +library, documented in the following subsections. -__Example__ +The library automatically discovers the region of a bucket by +default. This is especially useful with AWS, where buckets may be in +different regions. When performing an upload, download or other +operation, the library requests the service for the location of a +bucket and caches it for subsequent requests. -## Create client for MinIO +#### awsCI :: ConnectInfo -```js -var Minio = require('minio') +`awsCI` is a value that provides connection information for AWS +S3. Credentials can be supplied by overriding a couple of fields like +so: -var minioClient = new Minio.Client({ - endPoint: 'play.min.io', - port: 9000, - useSSL: true, - accessKey: 'Q3AM3UQ867SPQQA43P2F', - secretKey: 'zuf+tfteSlswRu7BJ86wekitnifILbZam1KYY3TG' -}); +``` haskell +awsConn = awsCI { + connectAccessKey = "my-AWS-access-key" + , connectSecretKey = "my-AWS-secret-key" + } ``` -## Create client for AWS S3 +#### awsWithRegionCI :: Region -> Bool -> ConnectInfo -```js -var Minio = require('minio') +This constructor allows to specify the initial region and a Boolean to +enable/disable the automatic region discovery behaviour. -var s3Client = new Minio.Client({ - endPoint: 's3.amazonaws.com', - accessKey: 'YOUR-ACCESSKEYID', - secretKey: 'YOUR-SECRETACCESSKEY' -}) +The parameters in the expression `awsWithRegion region autoDiscover` are: + +| Parameter | Type | Description | +|:---------------|:----------------------------|:---------------------------------------------------------------------------------------------------------------------------| +| `region` | _Region_ (alias for `Text`) | The region to connect to by default for all requests. | +| `autoDiscover` | _Bool_ | If `True`, region discovery will be enabled. If `False`, discovery is disabled, and all requests go the given region only. | + +#### minioPlayCI :: ConnectInfo + +This constructor provides connection and authentication information to +connect to the public MinIO Play server at +`https://play.min.io/`. + +#### minioCI :: Text -> Int -> Bool -> ConnectInfo + +Use to connect to a MinIO server. + +The parameters in the expression `minioCI host port isSecure` are: + +| Parameter | Type | Description | +|:-----------|:-------|:--------------------------------------------------------| +| `host` | _Text_ | Hostname of the MinIO or other S3-API compatible server | +| `port` | _Int_ | Port number to connect to | +| `isSecure` | _Bool_ | Does the server use HTTPS? | + +#### The ConnectInfo fields and Default instance + +The following table shows the fields in the `ConnectInfo` record-type: + +| Field | Type | Description | +|:----------------------------|:----------------------------|:--------------------------------------------------------------------------------------------------| +| `connectHost` | _Text_ | Host name of the server. Defaults to `localhost`. | +| `connectPort` | _Int_ | Port number on which the server listens. Defaults to `9000`. | +| `connectAccessKey` | _Text_ | Access key to use in authentication. Defaults to `minio`. | +| `connectSecretkey` | _Text_ | Secret key to use in authentication. Defaults to `minio123`. | +| `connectIsSecure` | _Bool_ | Specifies if the server used TLS. Defaults to `False` | +| `connectRegion` | _Region_ (alias for `Text`) | Specifies the region to use. Defaults to 'us-east-1' | +| `connectAutoDiscoverRegion` | _Bool_ | Specifies if the library should automatically discover the region of a bucket. Defaults to `True` | + +The `def` value of type `ConnectInfo` has all the above default +values. + +### The Minio Monad + +This monad provides the required environment to perform requests +against a MinIO or other S3 API compatible server. It uses the +connection information from the `ConnectInfo` value provided to it. It +performs connection pooling, bucket location caching, error handling +and resource clean-up actions. + +The `runMinio` function performs the provided action in the `Minio` +monad and returns a `IO (Either MinioErr a)` value: + +``` haskell +{-# Language OverloadedStrings #-} + +import Network.Minio + +main :: IO () +main = do + result <- runMinio def $ do + buckets <- listBuckets + return $ length buckets + + case result of + Left e -> putStrLn $ "Failed operation with error: " ++ show e + Right n -> putStrLn $ show n ++ " bucket(s) found." ``` -## Create client with temporary credentials - -```js -var Minio = require('minio') - -var s3Client = new Minio.Client({ - endPoint: 's3.amazonaws.com', - accessKey: 'YOUR-TEMP-ACCESSKEYID', - secretKey: 'YOUR-TEMP-SECRETACCESSKEY', - sessionToken: 'YOUR-TEMP-SESSIONTOKEN' -}) -``` +The above performs a `listBuckets` operation and returns the number of +buckets in the server. If there were any errors, they will be returned +as values of type `MinioErr` as a `Left` value. ## 2. Bucket operations - - -### makeBucket(bucketName, region[, makeOpts , callback]) - -Creates a new bucket. - -__Parameters__ - -| Param | Type | Description | -|-----------------|------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------| -| `bucketName` | _string_ | Name of the bucket. | -| `region` | _string_ | Region where the bucket is created. This parameter is optional. Default value is us-east-1. | -| `makeOpts` | _object_ | Options to create a bucket. e.g `{ObjectLocking:true}` (Optional) | -| `callback(err)` | _function_ | Callback function with `err` as the error argument. `err` is null if the bucket is successfully created. If no callback is passed, a `Promise` is returned. | - -__Example__ - -```js -minioClient.makeBucket('mybucket', 'us-east-1', function(err) { - if (err) return console.log('Error creating bucket.', err) - console.log('Bucket created successfully in "us-east-1".') -}) -``` - -__Example 1__ -Create a bucket with object locking enabled. - -```js -minioClient.makeBucket('mybucket', 'us-east-1', { ObjectLocking:true }, function(err) { - if (err) return console.log('Error creating bucket with object lock.', err) - console.log('Bucket created successfully in "us-east-1" and enabled object lock') -}) -``` -### listBuckets([callback]) +### listBuckets :: Minio [BucketInfo] +Lists buckets. -Lists all buckets. +__Return Value__ +| Return type | Description | +|:---------------------|:----------------| +| _Minio [BucketInfo]_ | List of buckets | + + +__BucketInfo record type__ + +| Field | Type | Description | +|:-----------------|:---------------------------|:----------------------------| +| `biName` | _Bucket_ (alias of `Text`) | Name of the bucket | +| `biCreationDate` | _UTCTime_ | Creation time of the bucket | + + + +### makeBucket :: Bucket -> Maybe Region -> Minio () + +Create a new bucket. If the region is not specified, the region +specified by `ConnectInfo` is used. __Parameters__ +In the expression `makeBucket bucketName region` the arguments are: -| Param | Type | Description | -|---|---|---| -|`callback(err, bucketStream) ` | _function_ | Callback function with error as the first argument. `bucketStream` is the stream emitting bucket information. If no callback is passed, a `Promise` is returned. | +| Param | Type | Description | +|--------------|-----------------------------|-----------------------------------------------------------------------------------------------------| +| `bucketName` | _Bucket_ (alias for `Text`) | Name of the bucket | +| `region` | _Maybe Region_ | Region where the bucket is to be created. If not specified, default to the region in `ConnectInfo`. | -bucketStream emits Object with the format:- +__Example__ -| Param | Type | Description | -|-----------------------|----------|-------------------------------| -| `bucket.name` | _string_ | bucket name | -| `bucket.creationDate` | _Date_ | date when bucket was created. | +``` haskell +{-# Language OverloadedStrings #-} +main :: IO () +main = do + res <- runMinio minioPlayCI $ do + makeBucket bucketName (Just "us-east-1") + case res of + Left err -> putStrLn $ "Failed to make bucket: " ++ (show res) + Right _ -> putStrLn $ "makeBucket successful." + +``` + + +### removeBucket :: Bucket -> Minio () + +Remove a bucket. The bucket must be empty or an error will be thrown. + +__Parameters__ + +In the expression `removeBucket bucketName` the arguments are: + +| Param | Type | Description | +|--------------|-----------------------------|--------------------| +| `bucketName` | _Bucket_ (alias for `Text`) | Name of the bucket | __Example__ -```js -minioClient.listBuckets(function(err, buckets) { - if (err) return console.log(err) - console.log('buckets :', buckets) -}) +``` haskell +{-# Language OverloadedStrings #-} + +main :: IO () +main = do + res <- runMinio minioPlayCI $ do + removeBucket "mybucket" + + case res of + Left err -> putStrLn $ "Failed to remove bucket: " ++ (show res) + Right _ -> putStrLn $ "removeBucket successful." + ``` - -#### bucketExists(bucketName[, callback]) + +### listObjects :: Bucket -> Maybe Text -> Bool -> C.ConduitM () ObjectInfo Minio () + +List objects in the given bucket, implements version 2 of AWS S3 API. + +__Parameters__ + +In the expression `listObjects bucketName prefix recursive` the +arguments are: + +| Param | Type | Description | +|:-------------|:----------------------------|:---------------------------------------------------------------------------------------------------------| +| `bucketName` | _Bucket_ (alias for `Text`) | Name of the bucket | +| `prefix` | _Maybe Text_ | Optional prefix that listed objects should have | +| `recursive` | _Bool_ | `True` indicates recursive style listing and `False` indicates directory style listing delimited by '/'. | + +__Return Value__ + +| Return type | Description | +|:------------------------------------|:------------------------------------------------------------------------| +| _C.ConduitM () ObjectInfo Minio ()_ | A Conduit Producer of `ObjectInfo` values corresponding to each object. | + +__ObjectInfo record type__ + +| Field | Type | Description | +|:-------------|:----------------------------|:-------------------------------------| +| `oiObject` | _Object_ (alias for `Text`) | Name of object | +| `oiModTime` | _UTCTime_ | Last modified time of the object | +| `oiETag` | _ETag_ (alias for `Text`) | ETag of the object | +| `oiSize` | _Int64_ | Size of the object in bytes | +| `oiMetadata` | _HashMap Text Text_ | Map of key-value user-metadata pairs | + +__Example__ + +``` haskell +{-# LANGUAGE OverloadedStrings #-} +import Network.Minio + +import Conduit +import Prelude + + +-- | The following example uses MinIO play server at +-- https://play.min.io. The endpoint and associated +-- credentials are provided via the libary constant, +-- +-- > minioPlayCI :: ConnectInfo +-- + +main :: IO () +main = do + let + bucket = "test" + + -- Performs a recursive listing of all objects under bucket "test" + -- on play.min.io. + res <- runMinio minioPlayCI $ + runConduit $ listObjects bucket Nothing True .| mapM_C (\v -> (liftIO $ print v)) + print res +``` + + +### listObjectsV1 :: Bucket -> Maybe Text -> Bool -> C.ConduitM () ObjectInfo Minio () + +List objects in the given bucket, implements version 1 of AWS S3 API. This API +is provided for legacy S3 compatible object storage endpoints. + +__Parameters__ + +In the expression `listObjectsV1 bucketName prefix recursive` the +arguments are: + +| Param | Type | Description | +|:-------------|:----------------------------|:---------------------------------------------------------------------------------------------------------| +| `bucketName` | _Bucket_ (alias for `Text`) | Name of the bucket | +| `prefix` | _Maybe Text_ | Optional prefix that listed objects should have | +| `recursive` | _Bool_ | `True` indicates recursive style listing and `False` indicates directory style listing delimited by '/'. | + +__Return Value__ + +| Return type | Description | +|:------------------------------------|:------------------------------------------------------------------------| +| _C.ConduitM () ObjectInfo Minio ()_ | A Conduit Producer of `ObjectInfo` values corresponding to each object. | + +__ObjectInfo record type__ + +| Field | Type | Description | +|:------------|:----------------------------|:---------------------------------| +| `oiObject` | _Object_ (alias for `Text`) | Name of object | +| `oiModTime` | _UTCTime_ | Last modified time of the object | +| `oiETag` | _ETag_ (alias for `Text`) | ETag of the object | +| `oiSize` | _Int64_ | Size of the object in bytes | + +__Example__ + +``` haskell +{-# LANGUAGE OverloadedStrings #-} +import Network.Minio + +import Conduit +import Prelude + + +-- | The following example uses MinIO play server at +-- https://play.min.io. The endpoint and associated +-- credentials are provided via the libary constant, +-- +-- > minioPlayCI :: ConnectInfo +-- + +main :: IO () +main = do + let + bucket = "test" + + -- Performs a recursive listing of all objects under bucket "test" + -- on play.min.io. + res <- runMinio minioPlayCI $ + runConduit $ listObjectsV1 bucket Nothing True .| mapM_C (\v -> (liftIO $ print v)) + print res +``` + + +### listIncompleteUploads :: Bucket -> Maybe Prefix -> Bool -> C.Producer Minio UploadInfo + +List incompletely uploaded objects. + +__Parameters__ + +In the expression `listIncompleteUploads bucketName prefix recursive` +the parameters are: + +| Param | Type | Description | +|:-------------|:----------------------------|:---------------------------------------------------------------------------------------------------------| +| `bucketName` | _Bucket_ (alias for `Text`) | Name of the bucket | +| `prefix` | _Maybe Text_ | Optional prefix that listed objects should have. | +| `recursive` | _Bool_ | `True` indicates recursive style listing and `Talse` indicates directory style listing delimited by '/'. | + +__Return Value__ + +|Return type |Description | +|:---|:---| +| _C.ConduitM () UploadInfo Minio ()_ | A Conduit Producer of `UploadInfo` values corresponding to each incomplete multipart upload | + +__UploadInfo record type__ + +| Field | Type | Description | +|:-------------|:---------|:------------------------------------------| +| `uiKey` | _Object_ | Name of incompletely uploaded object | +| `uiUploadId` | _String_ | Upload ID of incompletely uploaded object | +| `uiSize` | _Int64_ | Size of incompletely uploaded object | + +__Example__ + +```haskell +{-# LANGUAGE OverloadedStrings #-} +import Network.Minio + +import Conduit +import Prelude + +-- | The following example uses MinIO play server at +-- https://play.min.io. The endpoint and associated +-- credentials are provided via the libary constant, +-- +-- > minioPlayCI :: ConnectInfo +-- + +main :: IO () +main = do + let + bucket = "test" + + -- Performs a recursive listing of incomplete uploads under bucket "test" + -- on a local MinIO server. + res <- runMinio minioPlayCI $ + runConduit $ listIncompleteUploads bucket Nothing True .| mapM_C (\v -> (liftIO $ print v)) + print res + +``` + +## 3. Object operations + + +### getObject :: Bucket -> Object -> GetObjectOptions -> Minio (C.ConduitM () ByteString Minio ()) + +Get an object from the S3 service, optionally object ranges can be provided as well. + +__Parameters__ + +In the expression `getObject bucketName objectName opts` the parameters +are: + +| Param | Type | Description | +|:-------------|:----------------------------|:----------------------------------------------------------------------------| +| `bucketName` | _Bucket_ (alias for `Text`) | Name of the bucket | +| `objectName` | _Object_ (alias for `Text`) | Name of the object | +| `opts` | _GetObjectOptions_ | Options for GET requests specifying additional options like If-Match, Range | + +__GetObjectOptions record type__ + +| Field | Type | Description | +|:-----------------------|:--------------------------------|:------------------------------------------------------------------------------------------------------| +| `gooRange` | `Maybe ByteRanges` | Represents the byte range of object. E.g ByteRangeFromTo 0 9 represents first ten bytes of the object | +| `gooIfMatch` | `Maybe ETag` (alias for `Text`) | (Optional) ETag of object should match | +| `gooIfNoneMatch` | `Maybe ETag` (alias for `Text`) | (Optional) ETag of object shouldn't match | +| `gooIfUnmodifiedSince` | `Maybe UTCTime` | (Optional) Time since object wasn't modified | +| `gooIfModifiedSince` | `Maybe UTCTime` | (Optional) Time since object was modified | + +__Return Value__ + +The return value can be incrementally read to process the contents of +the object. +| Return type | Description | +|:--------------------------------------------|:-----------------------------------------| +| _Minio (C.ConduitM () ByteString Minio ())_ | A Conduit source of `ByteString` values. | + +__Example__ + +```haskell +{-# LANGUAGE OverloadedStrings #-} +import Network.Minio + +import qualified Data.Conduit as C +import qualified Data.Conduit.Binary as CB + +import Prelude + +-- | The following example uses MinIO play server at +-- https://play.min.io. The endpoint and associated +-- credentials are provided via the libary constant, +-- +-- > minioPlayCI :: ConnectInfo +-- + +main :: IO () +main = do + let + bucket = "my-bucket" + object = "my-object" + res <- runMinio minioPlayCI $ do + src <- getObject bucket object def + C.connect src $ CB.sinkFileCautious "/tmp/my-object" + + case res of + Left e -> putStrLn $ "getObject failed." ++ (show e) + Right _ -> putStrLn "getObject succeeded." +``` + + +### putObject :: Bucket -> Object -> C.ConduitM () ByteString Minio () -> Maybe Int64 -> PutObjectOptions -> Minio () +Uploads an object to a bucket in the service, from the given input +byte stream of optionally supplied length. Optionally you can also specify +additional metadata for the object. + +__Parameters__ + +In the expression `putObject bucketName objectName inputSrc` the parameters +are: + +| Param | Type | Description | +|:-------------|:------------------------------------|:------------------------------------------------------------------| +| `bucketName` | _Bucket_ (alias for `Text`) | Name of the bucket | +| `objectName` | _Object_ (alias for `Text`) | Name of the object | +| `inputSrc` | _C.ConduitM () ByteString Minio ()_ | A Conduit producer of `ByteString` values | +| `size` | _Int64_ | Provide stream size (optional) | +| `opts` | _PutObjectOptions_ | Optional parameters to provide additional metadata for the object | + +__Example__ + +```haskell +{-# LANGUAGE OverloadedStrings #-} +import Network.Minio + +import qualified Data.Conduit.Combinators as CC + +import Prelude + +-- | The following example uses MinIO play server at +-- https://play.min.io. The endpoint and associated +-- credentials are provided via the libary constant, +-- +-- > minioPlayCI :: ConnectInfo +-- + +main :: IO () +main = do + let + bucket = "test" + object = "obj" + localFile = "/etc/lsb-release" + kb15 = 15 * 1024 + + -- Eg 1. Upload a stream of repeating "a" using putObject with default options. + res <- runMinio minioPlayCI $ + putObject bucket object (CC.repeat "a") (Just kb15) def + case res of + Left e -> putStrLn $ "putObject failed." ++ show e + Right () -> putStrLn "putObject succeeded." + +``` + + +### fGetObject :: Bucket -> Object -> FilePath -> GetObjectOptions -> Minio () +Downloads an object from a bucket in the service, to the given file + +__Parameters__ + +In the expression `fGetObject bucketName objectName inputFile` the parameters +are: + +| Param | Type | Description | +|:-------------|:----------------------------|:----------------------------------------------------------------------------| +| `bucketName` | _Bucket_ (alias for `Text`) | Name of the bucket | +| `objectName` | _Object_ (alias for `Text`) | Name of the object | +| `inputFile` | _FilePath_ | Path to the file to be uploaded | +| `opts` | _GetObjectOptions_ | Options for GET requests specifying additional options like If-Match, Range | + + +__GetObjectOptions record type__ + +| Field | Type | Description | +|:-----------------------|:--------------------------------|:------------------------------------------------------------------------------------------------------| +| `gooRange` | `Maybe ByteRanges` | Represents the byte range of object. E.g ByteRangeFromTo 0 9 represents first ten bytes of the object | +| `gooIfMatch` | `Maybe ETag` (alias for `Text`) | (Optional) ETag of object should match | +| `gooIfNoneMatch` | `Maybe ETag` (alias for `Text`) | (Optional) ETag of object shouldn't match | +| `gooIfUnmodifiedSince` | `Maybe UTCTime` | (Optional) Time since object wasn't modified | +| `gooIfModifiedSince` | `Maybe UTCTime` | (Optional) Time since object was modified | + +``` haskell + +{-# Language OverloadedStrings #-} +import Network.Minio + +import Data.Conduit (($$+-)) +import Data.Conduit.Binary (sinkLbs) +import Prelude + +-- | The following example uses MinIO play server at +-- https://play.min.io. The endpoint and associated +-- credentials are provided via the libary constant, +-- +-- > minioPlayCI :: ConnectInfo +-- + +main :: IO () +main = do + let + bucket = "my-bucket" + object = "my-object" + localFile = "/etc/lsb-release" + + res <- runMinio minioPlayCI $ do + src <- fGetObject bucket object localFile def + (src $$+- sinkLbs) + + case res of + Left e -> putStrLn $ "fGetObject failed." ++ (show e) + Right _ -> putStrLn "fGetObject succeeded." +``` + + +### fPutObject :: Bucket -> Object -> FilePath -> Minio () +Uploads an object to a bucket in the service, from the given file + +__Parameters__ + +In the expression `fPutObject bucketName objectName inputFile` the parameters +are: + +| Param | Type | Description | +|:-------------|:----------------------------|:--------------------------------| +| `bucketName` | _Bucket_ (alias for `Text`) | Name of the bucket | +| `objectName` | _Object_ (alias for `Text`) | Name of the object | +| `inputFile` | _FilePath_ | Path to the file to be uploaded | + +__Example__ + +```haskell +{-# Language OverloadedStrings #-} +import Network.Minio +import qualified Data.Conduit.Combinators as CC + +main :: IO () +main = do + let + bucket = "mybucket" + object = "myobject" + localFile = "/etc/lsb-release" + + res <- runMinio minioPlayCI $ do + fPutObject bucket object localFile + + case res of + Left e -> putStrLn $ "Failed to fPutObject " ++ show bucket ++ "/" ++ show object + Right _ -> putStrLn "fPutObject was successful" +``` + + +### copyObject :: DestinationInfo -> SourceInfo -> Minio () +Copies content of an object from the service to another + +__Parameters__ + +In the expression `copyObject dstInfo srcInfo` the parameters +are: + +| Param | Type | Description | +|:----------|:------------------|:----------------------------------------------------------| +| `dstInfo` | _DestinationInfo_ | A value representing properties of the destination object | +| `srcInfo` | _SourceInfo_ | A value representing properties of the source object | + + +__SourceInfo record type__ + +| Field | Type | Description | +|:-----------------------|:-----------------------|:----------------------------------------------------------------------------------------------------------| +| `srcBucket` | `Bucket` | Name of source bucket | +| `srcObject` | `Object` | Name of source object | +| `srcRange` | `Maybe (Int64, Int64)` | (Optional) Represents the byte range of source object. (0, 9) represents first ten bytes of source object | +| `srcIfMatch` | `Maybe Text` | (Optional) ETag source object should match | +| `srcIfNoneMatch` | `Maybe Text` | (Optional) ETag source object shouldn't match | +| `srcIfUnmodifiedSince` | `Maybe UTCTime` | (Optional) Time since source object wasn't modified | +| `srcIfModifiedSince` | `Maybe UTCTime` | (Optional) Time since source object was modified | + +__Destination record type__ + +| Field | Type | Description | +|:------------|:---------|:-----------------------------------------------------| +| `dstBucket` | `Bucket` | Name of destination bucket in server-side copyObject | +| `dstObject` | `Object` | Name of destination object in server-side copyObject | + +__Example__ + +```haskell +{-# Language OverloadedStrings #-} +import Network.Minio + +main :: IO () +main = do + let + bucket = "mybucket" + object = "myobject" + objectCopy = "obj-copy" + + res <- runMinio minioPlayCI $ do + copyObject def { dstBucket = bucket, dstObject = objectCopy } def { srcBucket = bucket, srcObject = object } + + case res of + Left e -> putStrLn $ "Failed to copyObject " ++ show bucket ++ show "/" ++ show object + Right _ -> putStrLn "copyObject was successful" +``` + + +### removeObject :: Bucket -> Object -> Minio () +Removes an object from the service + +__Parameters__ + +In the expression `removeObject bucketName objectName` the parameters +are: + +| Param | Type | Description | +|:-------------|:----------------------------|:-------------------| +| `bucketName` | _Bucket_ (alias for `Text`) | Name of the bucket | +| `objectName` | _Object_ (alias for `Text`) | Name of the object | + +__Example__ + +```haskell +{-# Language OverloadedStrings #-} +import Network.Minio + +main :: IO () +main = do + let + bucket = "mybucket" + object = "myobject" + + res <- runMinio minioPlayCI $ do + removeObject bucket object + + case res of + Left e -> putStrLn $ "Failed to remove " ++ show bucket ++ "/" ++ show object + Right _ -> putStrLn "Removed object successfully" +``` + + +### removeIncompleteUpload :: Bucket -> Object -> Minio () +Removes an ongoing multipart upload of an object from the service + +__Parameters__ + +In the expression `removeIncompleteUpload bucketName objectName` the parameters +are: + +| Param | Type | Description | +|:-------------|:----------------------------|:-------------------| +| `bucketName` | _Bucket_ (alias for `Text`) | Name of the bucket | +| `objectName` | _Object_ (alias for `Text`) | Name of the object | + +__Example__ + +```haskell +{-# Language OverloadedStrings #-} +import Network.Minio + +main :: IO () +main = do + let + bucket = "mybucket" + object = "myobject" + + res <- runMinio minioPlayCI $ + removeIncompleteUpload bucket object + + case res of + Left _ -> putStrLn $ "Failed to remove " ++ show bucket ++ "/" ++ show object + Right _ -> putStrLn "Removed incomplete upload successfully" +``` + + +### selectObjectContent :: Bucket -> Object -> SelectRequest -> Minio (ConduitT () EventMessage Minio ()) +Removes an ongoing multipart upload of an object from the service + +__Parameters__ + +In the expression `selectObjectContent bucketName objectName selReq` +the parameters are: + +| Param | Type | Description | +|:-------------|:----------------------------|:--------------------------| +| `bucketName` | _Bucket_ (alias for `Text`) | Name of the bucket | +| `objectName` | _Object_ (alias for `Text`) | Name of the object | +| `selReq` | _SelectRequest_ | Select request parameters | + +__SelectRequest record__ + +This record is created using `selectRequest`. Please refer to the Haddocks for further information. + +__Return Value__ + +The return value can be used to read individual `EventMessage`s in the response. Please refer to the Haddocks for further information. + +|Return type | Description | +|:---|:---| +| _Minio (C.conduitT () EventMessage Minio ())_ | A Conduit source of `EventMessage` values. | + +__Example__ + +```haskell +{-# Language OverloadedStrings #-} +import Network.Minio + +import qualified Conduit as C + +main :: IO () +main = do + let + bucket = "mybucket" + object = "myobject" + + res <- runMinio minioPlayCI $ do + let sr = selectRequest "Select * from s3object" + defaultCsvInput defaultCsvOutput + res <- selectObjectContent bucket object sr + C.runConduit $ res C..| getPayloadBytes C..| C.stdoutC + + case res of + Left _ -> putStrLn "Failed!" + Right _ -> putStrLn "Success!" +``` + + + +### bucketExists :: Bucket -> Minio Bool Checks if a bucket exists. __Parameters__ +In the expression `bucketExists bucketName` the parameters are: -| Param | Type | Description | -|-------------------------|------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| `bucketName` | _string_ | Name of the bucket. | -| `callback(err, exists)` | _function_ | `exists` is a boolean which indicates whether `bucketName` exists or not. `err` is set when an error occurs during the operation. If no callback is passed, a `Promise` is returned. | - -__Example__ - - -```js -minioClient.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__ - - -| Param | Type | Description | -|-----------------|------------|-----------------------------------------------------------------------------------------------------------| -| `bucketName` | _string_ | Name of the bucket. | -| `callback(err)` | _function_ | `err` is `null` if the bucket is removed successfully. If no callback is passed, a `Promise` is returned. | - -__Example__ - - -```js -minioClient.removeBucket('mybucket', function(err) { - if (err) return console.log('unable to remove bucket.') - console.log('Bucket removed successfully.') -}) -``` - - -### listObjects(bucketName, prefix, recursive [,listOpts]) - -Lists all objects in a bucket. - -__Parameters__ - - -| Param | Type | Description | -|--------------|----------|---------------------------------------------------------------------------------------------------------------------------------------| -| `bucketName` | _string_ | Name of the bucket. | -| `prefix` | _string_ | The prefix of the objects that should be listed (optional, default `''`). | -| `recursive` | _bool_ | `true` indicates recursive style listing and `false` indicates directory style listing delimited by '/'. (optional, default `false`). | -| `listOpts` | _object_ | query params to list object which can have `{IncludeVersion: _bool_ }` (optional) | - -__Return Value__ - - -| Param | Type | Description | -| ---- | ---- | ---- | -| `stream` | _Stream_ | Stream emitting the objects in the bucket. | - -The object is of the format: - -| Param | Type | Description | -|----------------------|-----------|--------------------------------| -| `obj.name` | _string_ | name of the object. | -| `obj.prefix` | _string_ | name of the object prefix. | -| `obj.size` | _number_ | size of the object. | -| `obj.etag` | _string_ | etag of the object. | -| `obj.versionId` | _string_ | versionId of the object. | -| `obj.isDeleteMarker` | _boolean_ | true if it is a delete marker. | -| `obj.lastModified` | _Date_ | modified time stamp. | - -__Example__ - - -```js -var data = [] -var stream = minioClient.listObjects('mybucket','', true) -stream.on('data', function(obj) { data.push(obj) } ) -stream.on("end", function (obj) { console.log(data) }) -stream.on('error', function(err) { console.log(err) } ) -``` - -__Example1__ -To get Object versions - -```js -var data = [] -var stream = minioClient.listObjects('mybucket','', true, {IncludeVersion:true}) -stream.on('data', function(obj) { data.push(obj) } ) -stream.on("end", function (obj) { console.log(data) }) -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__ - - -| Param | Type | Description | -|--------------|----------|---------------------------------------------------------------------------------------------------------------------------------------| -| `bucketName` | _string_ | Name of the bucket. | -| `prefix` | _string_ | The prefix of the objects that should be listed (optional, default `''`). | -| `recursive` | _bool_ | `true` indicates recursive style listing and `false` indicates directory style listing delimited by '/'. (optional, default `false`). | -| `startAfter` | _string_ | Specifies the object name to start after when listing objects in a bucket. (optional, default `''`). | - - -__Return Value__ - -| Param | Type | Description | -|----------|----------|--------------------------------------------| -| `stream` | _Stream_ | Stream emitting the objects in the bucket. | - -The object is of the format: - -| Param | Type | Description | -|--------------------|----------|----------------------------| -| `obj.name` | _string_ | name of the object. | -| `obj.prefix` | _string_ | name of the object prefix. | -| `obj.size` | _number_ | size of the object. | -| `obj.etag` | _string_ | etag of the object. | -| `obj.lastModified` | _Date_ | modified time stamp. | - - -__Example__ - -```js -var stream = minioClient.listObjectsV2('mybucket','', true,'') -stream.on('data', function(obj) { console.log(obj) } ) -stream.on('error', function(err) { console.log(err) } ) -``` - - -### listObjectsV2WithMetadata(bucketName, prefix, recursive, startAfter) - -Lists all objects and their metadata in a bucket using S3 listing objects V2 API - -__Parameters__ - - -| Param | Type | Description | -|--------------|----------|---------------------------------------------------------------------------------------------------------------------------------------| -| `bucketName` | _string_ | Name of the bucket. | -| `prefix` | _string_ | The prefix of the objects that should be listed (optional, default `''`). | -| `recursive` | _bool_ | `true` indicates recursive style listing and `false` indicates directory style listing delimited by '/'. (optional, default `false`). | -| `startAfter` | _string_ | Specifies the object name to start after when listing objects in a bucket. (optional, default `''`). | - - -__Return Value__ - -| Param | Type | Description | -|----------|----------|--------------------------------------------| -| `stream` | _Stream_ | Stream emitting the objects in the bucket. | - -The object is of the format: - -| Param | Type | Description | -|--------------------|----------|----------------------------| -| `obj.name` | _string_ | name of the object. | -| `obj.prefix` | _string_ | name of the object prefix. | -| `obj.size` | _number_ | size of the object. | -| `obj.etag` | _string_ | etag of the object. | -| `obj.lastModified` | _Date_ | modified time stamp. | -| `obj.metadata` | _object_ | metadata of the object. | - -__Example__ - - -```js -var stream = minioClient.extensions.listObjectsV2WithMetadata('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__ - - -| Param | Type | Description | -|--------------|----------|---------------------------------------------------------------------------------------------------------------------------------------| -| `bucketName` | _string_ | Name of the bucket. | -| `prefix` | _string_ | Prefix of the object names that are partially uploaded. (optional, default `''`) | -| `recursive` | _bool_ | `true` indicates recursive style listing and `false` indicates directory style listing delimited by '/'. (optional, default `false`). | - -__Return Value__ - - -| Param | Type | Description | -|----------|----------|-------------------------------------------| -| `stream` | _Stream_ | Emits objects of the format listed below: | - -| Param | Type | Description | -|-----------------|-----------|----------------------------------------| -| `part.key` | _string_ | name of the object. | -| `part.uploadId` | _string_ | upload ID of the object. | -| `part.size` | _Integer_ | size of the partially uploaded object. | - -__Example__ - - -```js -var Stream = minioClient.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) -}) -``` - - -### getBucketVersioning(bucketName) - -Get Versioning state of a Bucket - -__Parameters__ - -| Param | Type | Description | -|----------------------|------------|----------------------------------------------------------------------------------------------------------------------------------| -| `bucketName` | _string_ | Name of the bucket. | -| `callback(err, res)` | _function_ | Callback is called with `err` in case of error. `res` is the response object. If no callback is passed, a `Promise` is returned. | - -__Example__ -```js -minioClient.getBucketVersioning('bucketname', function (err,res){ - if (err) { - return console.log(err) - } - console.log(res) - console.log("Success") -}) -``` - - -### setBucketVersioning(bucketName, versioningConfig, callback) - -Set Versioning state on a Bucket - -__Parameters__ - - -| Param | Type | Description | -|--------------------|------------|----------------------------------------------------| -| `bucketName` | _string_ | Name of the bucket. | -| `versioningConfig` | _object_ | Versioning Configuration e.g: `{Status:"Enabled"}` | -| `callback(err)` | _function_ | Callback is called with `err` in case of error. | - -__Example__ -```js -var versioningConfig = {Status:"Enabled"} -minioClient.setBucketVersioning('bucketname',versioningConfig, function (err){ - if (err) { - return console.log(err) - } - console.log("Success") -}) -``` - - - -### setBucketReplication(bucketName, replicationConfig, callback) - -Set replication config on a Bucket - -__Parameters__ - - -| Param | Type | Description | -|---------------------|------------|--------------------------------------------------| -| `bucketName` | _string_ | Name of the bucket. | -| `replicationConfig` | _object_ | replicationConfig Configuration as a JSON Object | -| `callback(err)` | _function_ | Callback is called with `err` in case of error. | - -__Example__ -```js -const arnFromMcCli = "arn:minio:replication::1277fcbe7df0bab76ab0c64cf7c45a0d27e01917ee5f11e913f3478417833660:destination" - -var replicationConfig = { - role:arnFromMcCli, - rules:[{ - "DeleteMarkerReplication": { - "Status": "Disabled" - }, - "DeleteReplication": { - "Status": [ - ] - }, - "Destination": { - "Bucket": "arn:aws:s3:::destination" - }, - "Priority": "1", - "Status": "Enabled" - }] -} - -minioClient.setBucketReplication('bucketname',replicationConfig, function (err){ - if (err) { - return console.log(err) - } - console.log("Success") -}) - -``` - - -### getBucketReplication(bucketName, callback) - -Get replication config of a Bucket - -__Parameters__ - - -| Param | Type | Description | -|------------------------------------|------------|----------------------------------------------------------------------------------------------------------------------------------------------------| -| `bucketName` | _string_ | Name of the bucket. | -| `callback(err, replicationConfig)` | _function_ | Callback is called with `err` in case of error. else returns the info in`replicationConfig` ,which contains`{role: __string__, rules:__Array__ }`. | - -__Example__ -```js -minioClient.getBucketReplication('bucketname', function (err,replicationConfig){ - if (err) { - return console.log(err) - } - console.log(replicationConfig) -}) - -``` - - -### removeBucketReplication(bucketName, callback) - -Remove replication config of a Bucket - -__Parameters__ - -| Param | Type | Description | -|-----------------|------------|-------------------------------------------------| -| `bucketName` | _string_ | Name of the bucket. | -| `callback(err)` | _function_ | Callback is called with `err` in case of error. | - -__Example__ -```js -minioClient.removeBucketReplication('bucketname', function (err,replicationConfig){ - if (err) { - return console.log(err) - } - console.log("Success") -}) - -``` - - -### setBucketTagging(bucketName, tags, callback) - -Set Tags on a Bucket - -__Parameters__ - -| Param | Type | Description | -|-----------------|------------|-----------------------------------------------------------| -| `bucketName` | _string_ | Name of the bucket. | -| `tags` | _object_ | Tags map Configuration e.g: `{:}` | -| `callback(err)` | _function_ | Callback is called with `err` in case of error. | - -__Example__ -```js -minioClient.setBucketTagging('bucketname',tags, function (err){ - if (err) { - return console.log(err) - } - console.log("Success") -}) -``` - - -### removeBucketTagging(bucketName, callback) - -Remove Tags on a Bucket - -__Parameters__ - -| Param | Type | Description | -|-----------------|------------|-------------------------------------------------| -| `bucketName` | _string_ | Name of the bucket. | -| `callback(err)` | _function_ | Callback is called with `err` in case of error. | - -__Example__ -```js -minioClient.removeBucketTagging('bucketname', function (err){ - if (err) { - return console.log(err) - } - console.log("Success") -}) -``` - - -### getBucketTagging(bucketName, callback) - -Remove Tags on a Bucket - -__Parameters__ - -| Param | Type | Description | -|---------------------------|------------|-------------------------------------------------| -| `bucketName` | _string_ | Name of the bucket. | -| `callback(err, tagsList)` | _function_ | Callback is called with `err` in case of error. | - -__Example__ -```js -minioClient.getBucketTagging('bucketname', function (err, tagsList){ - if (err) { - return console.log(err) - } - console.log("Success",tagsList) -}) -``` - - - -### setBucketLifecycle(bucketName, lifecycleConfig, callback) - -Set Lifecycle Configuration on a Bucket - -__Parameters__ - -| Param | Type | Description | -|-------------------|------------|------------------------------------------------------------------------------------| -| `bucketName` | _string_ | Name of the bucket. | -| `lifecycleConfig` | _object_ | Valid Lifecycle Configuration or ( `null` or `''` ) to remove policy configuration | -| `callback(err)` | _function_ | Callback is called with `err` in case of error. | - -__Example__ -```js -const lifecycleConfig= { - Rule: [{ - "ID": "Transition and Expiration Rule", - "Status": "Enabled", - "Filter": { - "Prefix":"", - }, - "Expiration": { - "Days": "3650" - } - } - ] -} - -minioClient.setBucketLifecycle('bucketname',lifecycleConfig, function (err) { - if (err) { - return console.log(err) - } - console.log("Success") -}) -``` - - - - -### getBucketLifecycle(bucketName, callback) - -Get Lifecycle Configuration of a Bucket - -__Parameters__ - -| Param | Type | Description | -|------------------------------------|------------|---------------------------------------------------------------------------------------------------| -| `bucketName` | _string_ | Name of the bucket. | -| `callback(error, lifecycleConfig)` | _function_ | Callback is called with `lifecycleConfig` in case of success. Otherwise it is called with `error` | - -__Example__ -```js -minioClient.getBucketLifecycle('bucketname', function (err, lifecycleConfig) { - if (err) { - return console.log(err) - } - console.log("Success", lifecycleConfig) -}) -``` - - -### removeBucketLifecycle(bucketName, callback) - -Remove Lifecycle Configuration of a Bucket - -__Parameters__ - -| Param | Type | Description | -|-----------------|------------|-------------------------------------------------| -| `bucketName` | _string_ | Name of the bucket. | -| `callback(err)` | _function_ | Callback is called with `err` in case of error. | - -__Example__ -```js - -minioClient.removeBucketLifecycle('bucketname', function (err) { - if (err) { - return console.log(err) - } - console.log("Success") -}) -``` - - - -### setObjectLockConfig(bucketName, lockConfig [, callback]) - -Set Object lock config on a Bucket - -__Parameters__ - - -| Param | Type | Description | -|-----------------|------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| `bucketName` | _string_ | Name of the bucket. | -| `lockConfig` | _object_ | Lock Configuration can be either `{}` to reset or object with all of the following key/value pairs: `{mode: ["COMPLIANCE"/'GOVERNANCE'], unit: ["Days"/"Years"], validity: }` | -| `callback(err)` | _function_ | Callback is called with `err` in case of error. | - -__Example 1__ - -```js -s3Client.setObjectLockConfig('my-bucketname', {mode:"COMPLIANCE", unit:'Days', validity:10 }, function (err){ - if (err) { - return console.log(err) - } - console.log("Success") -}) -``` - -__Example 2__ -To reset/remove object lock config on a bucket. - -```js -s3Client.setObjectLockConfig('my-bucketname', {}, function (err){ -if (err) { -return console.log(err) -} -console.log("Success") -}) -``` - - - -### getObjectLockConfig(bucketName [, callback]) - -Get Lock config on a Bucket - -__Parameters__ - - -| Param | Type | Description | -|-----------------------------|------------|-------------------------------------------------------------------------------------------| -| `bucketName` | _string_ | Name of the bucket. | -| `callback(err, lockConfig)` | _function_ | Callback is called with `err` in case of error. else it is called with lock configuration | - -__Example __ -Get object lock configuration on a Bucket - -```js -s3Client.getObjectLockConfig('my-bucketname', function (err, lockConfig){ - if (err) { - return console.log(err) - } - console.log(lockConfig) -}) -``` - - -### setBucketEncryption(bucketName [,encryptionConfig, callback]) - -Set encryption configuration on a Bucket - -__Parameters__ - - -| Param | Type | Description | -|--------------------|------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| `bucketName` | _string_ | Name of the bucket. | -| `encryptionConfig` | _object_ | Encryption Configuration can be either omitted or `{}` or a valid and supported encryption config. by default: `{Rule:[{ApplyServerSideEncryptionByDefault:{SSEAlgorithm:"AES256"}}]}` is applied. | -| `callback(err)` | _function_ | Callback is called with `err` in case of error. | - -__Example __ -Set Encryption configuration on a Bucket - -```js -s3Client.setBucketEncryption('my-bucketname', function (err, lockConfig){ - if (err) { - return console.log(err) - } - console.log(lockConfig) -}) -``` - -__Example 1__ -Set Encryption configuration on a Bucket with an Algorithm - -```js -s3Client.setBucketEncryption('my-bucketname',{Rule:[{ApplyServerSideEncryptionByDefault:{SSEAlgorithm:"AES256"}}]}, function (err, lockConfig){ - if (err) { - return console.log(err) - } - console.log("Success") -}) -``` - - -### getBucketEncryption(bucketName [, callback]) - -Get encryption configuration of a Bucket - -__Parameters__ - - -| Param | Type | Description | -|----------------------------|------------|-------------------------------------------------------------------------------------------| -| `bucketName` | _string_ | Name of the bucket. | -| `callback(err, encConfig)` | _function_ | Callback is called with `err` in case of error. else it is called with lock configuration | - -__Example __ -Get Encryption configuration of a Bucket - -```js -s3Client.getBucketEncryption('my-bucketname', function (err, encConfig){ - if (err) { - return console.log(err) - } - console.log(encConfig) -}) -``` - - -### removeBucketEncryption(bucketName [, callback]) - -Remove encryption configuration of a Bucket - -__Parameters__ - - -| Param | Type | Description | -|-----------------|------------|-------------------------------------------------| -| `bucketName` | _string_ | Name of the bucket. | -| `callback(err)` | _function_ | Callback is called with `err` in case of error. | - -__Example __ -Remove Encryption configuration of a Bucket - -```js -s3Client.removeBucketEncryption('my-bucketname', function (err){ - if (err) { - return console.log(err) - } - console.log("Success") -}) -``` - -## 3. Object operations - - -### getObject(bucketName, objectName, getOpts[, callback]) - -Downloads an object as a stream. - -__Parameters__ - - -| Param | Type | Description | -|-------------------------|------------|-------------------------------------------------------------------------------------------------------------------------------------------| -| `bucketName` | _string_ | Name of the bucket. | -| `objectName` | _string_ | Name of the object. | -| `getOpts` | _object_ | Version of the object in the form `{versionId:"my-versionId"}`. Default is `{}`. (optional) | -| `callback(err, stream)` | _function_ | Callback is called with `err` in case of error. `stream` is the object content stream. If no callback is passed, a `Promise` is returned. | - -__Return Value__ - -| Param | Type | Description | -|----------|----------|-------------------------------------| -| `stream` | _Stream_ | Stream emitting the object content. | - -__Example__ - - -```js -var size = 0 -minioClient.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) - }) -}) -``` - -__Example__ - -Get a specific object version. -```js -var size = 0 -minioClient.getObject('mybucket', 'photo.jpg', {versionId:"my-versionId"}, 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, getOpts[, callback]) - -Downloads the specified range bytes of an object as a stream. - -__Parameters__ - - -| Param | Type | Description | -|-------------------------|------------|-------------------------------------------------------------------------------------------------------------------------------------------| -| `bucketName` | _string_ | Name of the bucket. | -| `objectName` | _string_ | Name of the object. | -| `offset` | _number_ | `offset` of the object from where the stream will start. | -| `length` | _number_ | `length` of the object that will be read in the stream (optional, if not specified we read the rest of the file from the offset). | -| `getOpts` | _object_ | Version of the object in the form `{versionId:'my-versionId'}`. Default is `{}`. (optional) | -| `callback(err, stream)` | _function_ | Callback is called with `err` in case of error. `stream` is the object content stream. If no callback is passed, a `Promise` is returned. | - - -__Return Value__ - -| Param | Type | Description | -| ---- | ---- | ---- | -| `stream` | _Stream_ | Stream emitting the object content. | - -__Example__ - - -```js -var size = 0 -// reads 30 bytes from the offset 10. -minioClient.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) - }) -}) -``` -__Example__ -To get a specific version of an object - -```js -var versionedObjSize = 0 -// reads 30 bytes from the offset 10. -minioClient.getPartialObject('mybucket', 'photo.jpg', 10, 30, {versionId:"my-versionId"}, function(err, dataStream) { - if (err) { - return console.log(err) - } - dataStream.on('data', function(chunk) { - versionedObjSize += chunk.length - }) - dataStream.on('end', function() { - console.log('End. Total size = ' + versionedObjSize) - }) - dataStream.on('error', function(err) { - console.log(err) - }) -}) -``` - - - -### fGetObject(bucketName, objectName, filePath, getOpts[, callback]) - -Downloads and saves the object as a file in the local filesystem. - -__Parameters__ - -| Param | Type | Description | -|-----------------|------------|----------------------------------------------------------------------------------------------------| -| `bucketName` | _string_ | Name of the bucket. | -| `objectName` | _string_ | Name of the object. | -| `filePath` | _string_ | Path on the local filesystem to which the object data will be written. | -| `getOpts` | _object_ | Version of the object in the form `{versionId:'my-versionId'}`. Default is `{}`. (optional) | -| `callback(err)` | _function_ | Callback is called with `err` in case of error. If no callback is passed, a `Promise` is returned. | - -__Return Value__ - -| Value | Type | Description | -|--------|----------|--------------------------------------------------| -| `err` | _object_ | Error in case of any failures | -| `file` | _file_ | Streamed Output file at the specified `filePath` | - -__Example__ - - -```js -var size = 0 -minioClient.fGetObject('mybucket', 'photo.jpg', '/tmp/photo.jpg', function(err) { - if (err) { - return console.log(err) - } - console.log('success') -}) -``` - -__Example__ -To Stream a specific object version into a file. - -```js -minioClient.fGetObject(bucketName, objNameValue, './download/MyImage.jpg', {versionId:"my-versionId"}, function(e) { - if (e) { - return console.log(e) - } - console.log('success') -}) - -``` - - -### putObject(bucketName, objectName, stream, size, metaData[, callback]) - -Uploads an object from a stream/Buffer. - - -##### From a stream - -__Parameters__ - - -| Param | Type | Description | -|--------------------------|---------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| `bucketName` | _string_ | Name of the bucket. | -| `objectName` | _string_ | Name of the object. | -| `stream` | _Stream_ | Readable stream. | -| `size` | _number_ | Size of the object (optional). | -| `metaData` | _Javascript Object_ | metaData of the object (optional). | -| `callback(err, objInfo)` | _function_ | Non-null `err` indicates error, in case of Success,`objInfo` contains `etag` _string_ and `versionId` _string_ of the object. If no callback is passed, a `Promise` is returned. | - - -__Return Value__ - -| Value | Type | Description | -|---------------------|----------|-------------------------------------| -| `err` | _object_ | Error in case of any failures | -| `objInfo.etag` | _string_ | `etag` of an object | -| `objInfo.versionId` | _string_ | `versionId` of an object (optional) | - - -__Example__ - -The maximum size of a single object is limited to 5TB. putObject transparently uploads objects larger than 64MiB in multiple parts. Uploaded data is carefully verified using MD5SUM signatures. - -```js -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) - } - minioClient.putObject('mybucket', '40mbfile', fileStream, stats.size, function(err, objInfo) { - if(err) { - return console.log(err) // err should be null - } - console.log("Success", objInfo) - }) -}) -``` - -##### From a "Buffer" or a "string" - -__Parameters__ - - -| Param | Type | Description | -|-----------------------|----------------------|-------------------------------------------------------------------------------------| -| `bucketName` | _string_ | Name of the bucket. | -| `objectName` | _string_ | Name of the object. | -| `string or Buffer` | _Stream_ or _Buffer_ | Readable stream. | -| `metaData` | _Javascript Object_ | metaData of the object (optional). | -| `callback(err, etag)` | _function_ | Non-null `err` indicates error, `etag` _string_ is the etag of the object uploaded. | - - -__Example__ - - -```js -var buffer = 'Hello World' -minioClient.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__ - - -| Param | Type | Description | -|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------|----------------------------------| -| `bucketName` | _string_ | Name of the bucket. | -| `objectName` | _string_ | Name of the object. | -| `filePath` | _string_ | Path of the file to be uploaded. | -| `metaData` | _Javascript Object_ | Metadata of the object. | -| `callback(err, objInfo)` _function_: non null `err` indicates error, `objInfo` _object_ is the information about the object uploaded which contains `versionId` string and `etag` string. | | | - -__Return Value__ - -| Value | Type | Description | -|---------------------|----------|-------------------------------------| -| `err` | _object_ | Error in case of any failures | -| `objInfo.etag` | _string_ | `etag` of an object | -| `objInfo.versionId` | _string_ | `versionId` of an object (optional) | - -__Example__ - -The maximum size of a single object is limited to 5TB. fPutObject transparently uploads objects larger than 64MiB in multiple parts. Uploaded data is carefully verified using MD5SUM signatures. - -```js -var file = '/tmp/40mbfile' -var metaData = { - 'Content-Type': 'text/html', - 'Content-Language': 123, - 'X-Amz-Meta-Testing': 1234, - 'example': 5678 -} -minioClient.fPutObject('mybucket', '40mbfile', file, metaData, function(err, objInfo) { - if(err) { - return console.log(err) - } - console.log("Success", objInfo.etag, objInfo.versionId) -}) -``` - - -### copyObject(bucketName, objectName, sourceObject, conditions[, callback]) - -Copy a source object into a new object in the specified bucket. - -__Parameters__ - - -| Param | Type | Description | -|---------------------------------------|------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| `bucketName` | _string_ | Name of the bucket. | -| `objectName` | _string_ | Name of the object. | -| `sourceObject` | _string_ | Path of the file to be copied. | -| `conditions` | _CopyConditions_ | Conditions to be satisfied before allowing object copy. | -| `callback(err, {etag, lastModified})` | _function_ | Non-null `err` indicates error, `etag` _string_ and lastModified _Date_ are the etag and the last modified date of the object newly copied. If no callback is passed, a `Promise` is returned. | - -__Example__ - -```js -var conds = new Minio.CopyConditions() -conds.setMatchETag('bd891862ea3e22c93ed53a098218791d') -minioClient.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, statOpts[, callback]) - -Gets metadata of an object. - -__Parameters__ - - -| Param | Type | Description | -|-----------------------|------------|-----------------------------------------------------------------------------------------------------------------------------------------------| -| `bucketName` | _string_ | Name of the bucket. | -| `objectName` | _string_ | Name of the object. | -| `statOpts` | _object_ | Version of the object in the form `{versionId:"my-versionId"}`. Default is `{}`. (optional) | -| `callback(err, stat)` | _function_ | `err` is not `null` in case of error, `stat` contains the object information listed below. If no callback is passed, a `Promise` is returned. | - -__Return Value__ - -| Param | Type | Description | -|---------------------|---------------------|---------------------------| -| `stat.size` | _number_ | size of the object. | -| `stat.etag` | _string_ | etag of the object. | -| `stat.versionId` | _string_ | version of the object. | -| `stat.metaData` | _Javascript Object_ | metadata of the object. | -| `stat.lastModified` | _Date_ | Last Modified time stamp. | - - -__Example__ - - -```js -minioClient.statObject('mybucket', 'photo.jpg', function(err, stat) { - if (err) { - return console.log(err) - } - console.log(stat) -}) -``` - -__Example stat on a version of an object__ - - -```js -minioClient.statObject('mybucket', 'photo.jpg', { versionId : "my-versionId" }, function(err, stat) { - if (err) { - return console.log(err) - } - console.log(stat) -}) -``` - - -### removeObject(bucketName, objectName [, removeOpts] [, callback]) - -Removes an object. - -__Parameters__ - - -| Param | Type | Description | -|-----------------|------------|-------------------------------------------------------------------------------------------------------------------------------| -| `bucketName` | _string_ | Name of the bucket. | -| `objectName` | _string_ | Name of the object. | -| `removeOpts` | _object_ | Version of the object in the form `{versionId:"my-versionId", governanceBypass: true or false }`. Default is `{}`. (Optional) | -| `callback(err)` | _function_ | Callback function is called with non `null` value in case of error. If no callback is passed, a `Promise` is returned. | - -__Example 1__ - -```js -minioClient.removeObject('mybucket', 'photo.jpg', function(err) { - if (err) { - return console.log('Unable to remove object', err) - } - console.log('Removed the object') -}) -``` - -__Example 2__ -Delete a specific version of an object - -```js -minioClient.removeObject('mybucket', 'photo.jpg', { versionId : "my-versionId" }, function(err) { - if (err) { - return console.log('Unable to remove object', err) - } - console.log('Removed the object') -}) -``` - -__Example 3__ -Remove an object version locked with retention mode `GOVERNANCE` using the `governanceBypass` remove option - -```js -s3Client.removeObject('my-bucketname', 'my-objectname', {versionId:"my-versionId", governanceBypass:true}, function(e) { - if (e) { - return console.log(e) - } - console.log("Success") -}) - -``` - - -### removeObjects(bucketName, objectsList[, callback]) - -Remove all objects in the objectsList. - -__Parameters__ - - -| Param | Type | Description | -|-----------------|------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| `bucketName` | _string_ | Name of the bucket. | -| `objectsList` | _object_ | list of objects in the bucket to be removed. any one of the formats: 1. List of Object names as array of strings which are object keys: `['objectname1','objectname2']` 2. List of Object name and VersionId as an object: [{name:"my-obj-name",versionId:"my-versionId"}] | -| `callback(err)` | _function_ | Callback function is called with non `null` value in case of error. | - - -__Example__ - - -```js - -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') - }) - -}) - - -``` - -__Example1__ - -With versioning Support - -```js -var objectsList=[] -var bucket ="my-bucket" -var prefix="my-prefix" -var recursive=false - -var objectsStream = s3Client.listObjects(bucket, prefix, recursive, {IncludeVersion: true}) - objectsStream.on('data', function (obj) { - objectsList.push(obj) - }) - objectsStream.on('error', function (e) { - return console.log(e) - }) - objectsStream.on('end', function () { - s3Client.removeObjects(bucket, objectsList, function (e) { - if (e) { - return console.log(e) - } - console.log("Success") - }) - }) - -``` - - -### removeIncompleteUpload(bucketName, objectName[, callback]) - -Removes a partially uploaded object. - -__Parameters__ - - -| Param | Type | Description | -|-----------------|------------|------------------------------------------------------------------------------------------------------------------------| -| `bucketName` | _string_ | Name of the bucket. | -| `objectName` | _string_ | Name of the object. | -| `callback(err)` | _function_ | Callback function is called with non `null` value in case of error. If no callback is passed, a `Promise` is returned. | - - -__Example__ - - -```js -minioClient.removeIncompleteUpload('mybucket', 'photo.jpg', function(err) { - if (err) { - return console.log('Unable to remove incomplete object', err) - } - console.log('Incomplete object removed successfully.') -}) -``` - - - -### putObjectRetention(bucketName, objectName [, retentionOpts] [, callback]) - -Apply retention on an object. - -__Parameters__ - -| Param | Type | Description | -|-----------------|------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| `bucketName` | _string_ | Name of the bucket. | -| `objectName` | _string_ | Name of the object. | -| `retentionOpts` | _object_ | Options for retention like : `{ governanceBypass:true/false ,mode:COMPLIANCE/GOVERNANCE, retainUntilDate: _date_ , versionId:"my-versionId" }` Default is `{}` (Optional) | -| `callback(err)` | _function_ | Callback function is called with non `null` value in case of error. If no callback is passed, a `Promise` is returned. | - - -__Example__ -Apply object retention on an object - -```js -const bucketName = 'my-bucket' -const objectName ="my-object" - -const expirationDate = new Date() -expirationDate.setDate(expirationDate.getDate() + 1) -expirationDate.setUTCHours(0,0,0,0)//Should be start of the day.(midnight) -const versionId ="e67b4b08-144d-4fc4-ba15-43c3f7f9ba74" - -const objRetPromise = minioClient.putObjectRetention( - bucketName, - objectName, - { Mode:"GOVERNANCE", retainUntilDate:retainUntilDate.toISOString(), versionId:versionId }, - function (err){ - if (err) { - return console.log(err) - } - console.log("Success") -}) -``` - - -### getObjectRetention(bucketName, objectName [, getOpts] [, callback]) - -Get retention config of an object - -__Parameters__ - -| Param | Type | Description | -|----------------------|------------|----------------------------------------------------------------------------------------------------------------------------------| -| `bucketName` | _string_ | Name of the bucket. | -| `objectName` | _string_ | Name of the object. | -| `getOpts` | _object_ | Options for retention like : `{ versionId:"my-versionId" }` Default is `{}` (Optional) | -| `callback(err, res)` | _function_ | Callback is called with `err` in case of error. `res` is the response object. If no callback is passed, a `Promise` is returned. | - -__Example__ - -```js -minioClient.getObjectRetention('bucketname', 'bucketname', { versionId: "my-versionId" }, function (err, res){ - if (err) { - return console.log(err) - } - console.log(res) -}) -``` - - -### putObjectTagging(bucketName, objectName, tags[, putOpts, callback]) - -### setObjectTagging(bucketName, objectName, tags[, putOpts, callback]) - -Put Tags on an Object - -__Parameters__ - -| Param | Type | Description | -|-----------------|------------|---------------------------------------------------------------| -| `bucketName` | _string_ | Name of the bucket. | -| `objectName` | _string_ | Name of the object. | -| `tags` | _object_ | Tags map Configuration e.g: `{:}` | -| `putOpts` | _object_ | Default is {}. e.g `{versionId:"my-version-id"}`. (Optional) | -| `callback(err)` | _function_ | Callback is called with `err` in case of error. | - -__Example__ -```js -minioClient.setObjectTagging('bucketname','object-name', tags, function (err){ - if (err) { - return console.log(err) - } - console.log("Success") -}) -``` - -__Example 1__ -Put tags on a version of an object. - -```js -minioClient.setObjectTagging('bucketname','object-name', tags, { versionId: "my-version-id" }, function (err){ - if (err) { - return console.log(err) - } - console.log("Success") -}) -``` - - -### removeObjectTagging(bucketName, objectName[, removeOpts, callback]) - -Remove Tags on an Object - -__Parameters__ - -| Param | Type | Description | -|-----------------|------------|---------------------------------------------------------------| -| `bucketName` | _string_ | Name of the bucket. | -| `objectName` | _string_ | Name of the object. | -| `removeOpts` | _object_ | Defaults to {}. e.g `{versionId:"my-version-id"}`. (Optional) | -| `callback(err)` | _function_ | Callback is called with `err` in case of error. | - -__Example__ -```js -minioClient.removeObjectTagging('bucketname','object-name', function (err){ - if (err) { - return console.log(err) - } - console.log("Success") -}) -``` - - -__Example1__ -Remove tags on a version of an object. - -```js -minioClient.removeObjectTagging('bucketname', 'object-name', {versionId:"my-object-version-id"}, function (err){ - if (err) { - return console.log(err) - } - console.log("Success") -}) -``` - - -### getObjectTagging(bucketName, objectName[, getOpts, callback]) - -Get Tags of an Object - -__Parameters__ - -| Param | Type | Description | -|-----------------|------------|---------------------------------------------------------------| -| `bucketName` | _string_ | Name of the bucket. | -| `objectName` | _string_ | Name of the object. | -| `getOpts` | _object_ | Defaults to {}. e.g `{versionId:"my-version-id"}`. (Optional) | -| `callback(err)` | _function_ | Callback is called with `err` in case of error. | - -__Example__ -```js -minioClient.getObjectTagging('bucketname', 'object-name', function (err, tagsList){ - if (err) { - return console.log(err) - } - console.log("Success", tagsList) -}) -``` - - -__Example1__ -Get tags on a version of an object. - -```js -minioClient.getObjectTagging('bucketname', 'object-name', {versionId:"my-object-version-id"}, function (err, tagsList){ - if (err) { - return console.log(err) - } - console.log("Success", tagsList) -}) -``` - - -### getObjectLegalHold(bucketName, objectName, getOpts [, callback]) - -Get legal hold on an object. - -__Parameters__ - - -| Param | Type | Description | -|-----------------|------------|------------------------------------------------------------------------------------------------------------------------| -| `bucketName` | _string_ | Name of the bucket. | -| `objectName` | _string_ | Name of the object. | -| `getOpts` | _object_ | Legal hold configuration options. e.g `{versionId:'my-version-uuid'}` defaults to `{}` . | -| `callback(err)` | _function_ | Callback function is called with non `null` value in case of error. If no callback is passed, a `Promise` is returned. | - - -__Example 1__ - -Get Legal hold of an object. - -```js -minioClient.getObjectLegalHold('bucketName', 'objectName', {}, function(err, res) { - if (err) { - return console.log('Unable to get legal hold config for the object', err.message) - } - console.log('Success', res) -}) -``` - -__Example 2__ - -Get Legal hold of an object with versionId. - -```js -minioClient.getObjectLegalHold('bucketName', 'objectName', { versionId:'my-obj-version-uuid' }, function(err, res) { - if (err) { - return console.log('Unable to get legal hold config for the object', err.message) - } - console.log('Success', res) -}) -``` - - - -### setObjectLegalHold(bucketName, objectName, [,setOpts, callback]) - -Set legal hold on an object. - -__Parameters__ - - -| Param | Type | Description | -|-----------------|------------|---------------------------------------------------------------------------------------------------------------------------------------------| -| `bucketName` | _string_ | Name of the bucket. | -| `objectName` | _string_ | Name of the object. | -| `setOpts` | _object_ | Legal hold configuration options to set. e.g `{versionId:'my-version-uuid', status:'ON or OFF'}` defaults to `{status:'ON'}` if not passed. | -| `callback(err)` | _function_ | Callback function is called with non `null` value in case of error. If no callback is passed, a `Promise` is returned. | - -__Example 1__ - -Set Legal hold of an object. -```js -minioClient.setObjectLegalHold('bucketName', 'objectName', {Status:"ON"}, function(err, res) { - if (err) { - return console.log('Unable to set legal hold config for the object', err.message) - } - console.log('Success') -}) -``` - -__Example 2__ - -Set Legal hold of an object with versionId. -```js -minioClient.setObjectLegalHold('bucketName', 'objectName', { Status:"ON", versionId:'my-obj-version-uuid' }, function(err, res) { - if (err) { - return console.log('Unable to set legal hold config for the object version', err.message) - } - console.log('Success') -}) -``` - - - -### composeObject(destObjConfig, sourceObjectList [, callback]) - -Compose an object from parts - -__Parameters__ - - -| Param | Type | Description | -|--------------------|------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| `destObjConfig` | _object_ | Destination Object configuration of the type [CopyDestinationOptions](https://github.com/minio/minio-js/blob/master/src/helpers.js) | -| `sourceObjectList` | _object[]_ | Array of object(parts) source to compose into an object. Each part configuration should be of type [CopySourceOptions](https://github.com/minio/minio-js/blob/master/src/helpers.js) | -| `callback(err)` | _function_ | Callback function is called with non `null` value in case of error. If no callback is passed, a `Promise` is returned. | - - -__Example 1__ - -Compose an Object from its parts . - -```js -const sourceList = [new Helpers.CopySourceOptions( { - Bucket: "source-bucket", - Object: "parta", -}),new Helpers.CopySourceOptions({ - Bucket: "source-bucket", - Object: "partb", -}),new Helpers.CopySourceOptions({ - Bucket: "source-bucket", - Object: "partc", - -}),new Helpers.CopySourceOptions({ - Bucket: "source-bucket", - Object: "partd", -})] - -const destOption = new Helpers.CopyDestinationOptions({ - Bucket: "dest-bucket", - Object: "100MB.zip" -}) - -//using Promise style. -const composePromise = minioClient.composeObject(destOption,sourceList) - composePromise.then((result) => { - console.log("Success...") - }) - .catch((e)=>{ - console.log("error",e) - }) - -``` - - -### selectObjectContent(bucketName, objectName, selectOpts[, callback]) - -Select contents of an object (S3 Select). - -__Parameters__ - -| Param | Type | Description | -|-----------------|------------|------------------------------------------------------------------------------------------------------------------------------------------------------| -| `bucketName` | _string_ | Name of the bucket. | -| `objectName` | _string_ | Name of the object. | -| `selectOpts` | _object_ | | -| `callback(err)` | _function_ | Callback function is called with non `null` value in case of error. If no callback is passed, a `Promise` is returned, with the `SelectResults` type | - -__Example 1__ -Select all values -```js -const selectOpts = { - expression:"SELECT * FROM s3object s where s.\"Name\" = 'Jane'", - expressionType:"SQL", - inputSerialization : {'CSV': {"FileHeaderInfo": "Use", - RecordDelimiter: "\n", - FieldDelimiter: ",", - }, - 'CompressionType': 'NONE'}, - outputSerialization : {'CSV': {RecordDelimiter: "\n", - FieldDelimiter: ",",}}, - requestProgress:{Enabled:true}, -} - -minioClient.selectObjectContent('bucketName', 'objectName', selectOpts, function(err, res) { - if (err) { - return console.log('Unable to process select object content.', err.message) - } - console.log('Success') -}) -``` +| Param | Type | Description | +|:-------------|:----------------------------|:-------------------| +| `bucketName` | _Bucket_ (alias for `Text`) | Name of the bucket | ## 4. Presigned operations -Presigned URLs are generated for temporary download/upload access to private objects. + +### presignedGetObjectUrl :: Bucket -> Object -> UrlExpiry -> Query -> RequestHeaders -> Minio ByteString - -### 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. +Generate a URL with authentication signature to GET (download) an +object. All extra query parameters and headers passed here will be +signed and are required when the generated URL is used. Query +parameters could be used to change the response headers sent by the +server. Headers can be used to set Etag match conditions among others. +For a list of possible request parameters and headers, please refer +to the GET object REST API AWS S3 documentation. __Parameters__ +In the expression `presignedGetObjectUrl bucketName objectName expiry queryParams headers` +the parameters are: +| Param | Type | Description | +|:--------------|:---------------------------------------------------------------|:------------------------------------------------| +| `bucketName` | _Bucket_ (alias for `Text`) | Name of the bucket | +| `objectName` | _Object_ (alias for `Text`) | Name of the object | +| `expiry` | _UrlExpiry_ (alias for `Int`) | Url expiry time in seconds | +| `queryParams` | _Query_ (from package `http-types:Network.HTTP.Types`) | Query parameters to add to the URL | +| `headers` | _RequestHeaders_ (from package `http-types:Network.HTTP.Types` | Request headers that would be used with the URL | -| Param | Type | Description | -|-------------------------------|------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| `bucketName` | _string_ | Name of the bucket. | -| `objectName` | _string_ | Name of the object. | -| `expiry` | _number_ | Expiry time in seconds. Default value is 7 days. (optional) | -| `reqParams` | _object_ | request parameters. (optional) e.g {versionId:"10fa9946-3f64-4137-a58f-888065c0732e"} | -| `requestDate` | _Date_ | A date object, the url will be issued at. Default value is now. (optional) | -| `callback(err, presignedUrl)` | _function_ | Callback function is called with non `null` err value in case of error. `presignedUrl` will be the URL using which the object can be downloaded using GET request. If no callback is passed, a `Promise` is returned. | +__Return Value__ +Returns the generated URL - it will include authentication +information. -__Example1__ - - -```js -// presigned url for 'getObject' method. -// expires in a day. -minioClient.presignedUrl('GET', 'mybucket', 'hello.txt', 24*60*60, function(err, presignedUrl) { - if (err) return console.log(err) - console.log(presignedUrl) -}) -``` - - -__Example2__ - - -```js -// presigned url for 'listObject' method. -// Lists objects in 'myBucket' with prefix 'data'. -// Lists max 1000 of them. -minioClient.presignedUrl('GET', 'mybucket', '', 1000, {'prefix': 'data', 'max-keys': 1000}, function(err, presignedUrl) { - if (err) return console.log(err) - console.log(presignedUrl) -}) -``` - -__Example 3__ - - -```js -// Get Object with versionid -minioClient.presignedUrl('GET', 'mybucket', '', 1000, {versionId: "10fa9946-3f64-4137-a58f-888065c0732e"}, 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__ - - - -| Param | Type | Description | -|-------------------------------|------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| `bucketName` | _string_ | Name of the bucket. | -| `objectName` | _string_ | Name of the object. | -| `expiry` | _number_ | Expiry time in seconds. Default value is 7 days. (optional) | -| `respHeaders` | _object_ | response headers to override (optional) | -| `requestDate` | _Date_ | A date object, the url will be issued at. Default value is now. (optional) | -| `callback(err, presignedUrl)` | _function_ | Callback function is called with non `null` err value in case of error. `presignedUrl` will be the URL using which the object can be downloaded using GET request. If no callback is passed, a `Promise` is returned. | - +| Return type | Description | +|:-------------|:------------------------| +| _ByteString_ | Generated presigned URL | __Example__ +```haskell +{-# Language OverloadedStrings #-} -```js -// expires in a day. -minioClient.presignedGetObject('mybucket', 'hello.txt', 24*60*60, function(err, presignedUrl) { - if (err) return console.log(err) - console.log(presignedUrl) -}) +import Network.Minio +import qualified Data.ByteString.Char8 as B + +main :: IO () +main = do + let + bucket = "mybucket" + object = "myobject" + + res <- runMinio minioPlayCI $ do + -- Set a 7 day expiry for the URL + presignedGetObjectUrl bucket object (7*24*3600) [] [] + + -- Print the URL on success. + putStrLn $ either + (("Failed to generate URL: " ++) . show) + B.unpack + res ``` - -### presignedPutObject(bucketName, objectName, expiry[, callback]) + +### presignedPutObjectUrl :: Bucket -> Object -> UrlExpiry -> RequestHeaders -> Minio ByteString -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. +Generate a URL with authentication signature to PUT (upload) an +object. Any extra headers if passed, are signed, and so they are +required when the URL is used to upload data. This could be used, for +example, to set user-metadata on the object. +For a list of possible headers to pass, please refer to the PUT object +REST API AWS S3 documentation. __Parameters__ +In the expression `presignedPutObjectUrl bucketName objectName expiry headers` +the parameters are: -| Param | Type | Description | -|-------------------------------|------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| `bucketName` | _string_ | Name of the bucket. | -| `objectName` | _string_ | Name of the object. | -| `expiry` | _number_ | Expiry time in seconds. Default value is 7 days. | -| `callback(err, presignedUrl)` | _function_ | Callback function is called with non `null` err value in case of error. `presignedUrl` will be the URL using which the object can be uploaded using PUT request. If no callback is passed, a `Promise` is returned. | +| Param | Type | Description | +|:-------------|:---------------------------------------------------------------|:------------------------------------------------| +| `bucketName` | _Bucket_ (alias for `Text`) | Name of the bucket | +| `objectName` | _Object_ (alias for `Text`) | Name of the object | +| `expiry` | _UrlExpiry_ (alias for `Int`) | Url expiry time in seconds | +| `headers` | _RequestHeaders_ (from package `http-types:Network.HTTP.Types` | Request headers that would be used with the URL | +__Return Value__ + +Returns the generated URL - it will include authentication +information. + +| Return type | Description | +|:-------------|:------------------------| +| _ByteString_ | Generated presigned URL | __Example__ +```haskell +{-# Language OverloadedStrings #-} -```js -// expires in a day. -minioClient.presignedPutObject('mybucket', 'hello.txt', 24*60*60, function(err, presignedUrl) { - if (err) return console.log(err) - console.log(presignedUrl) -}) +import Network.Minio +import qualified Data.ByteString.Char8 as B + +main :: IO () +main = do + let + bucket = "mybucket" + object = "myobject" + + res <- runMinio minioPlayCI $ do + -- Set a 7 day expiry for the URL + presignedPutObjectUrl bucket object (7*24*3600) [] [] + + -- Print the URL on success. + putStrLn $ either + (("Failed to generate URL: " ++) . show) + B.unpack + res ``` -### presignedPostPolicy(policy[, callback]) +### presignedPostPolicy :: PostPolicy -> Minio (ByteString, HashMap Text ByteString) -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. +Generate a presigned URL and POST policy to upload files via a POST +request. This is intended for browser uploads and generates form data +that should be submitted in the request. -__Parameters__ +The `PostPolicy` argument is created using the `newPostPolicy` function: +#### newPostPolicy :: UTCTime -> [PostPolicyCondition] -> Either PostPolicyError PostPolicy -| Param | Type | Description | -|--------------------------------------|------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| `policy` | _object_ | Policy object created by minioClient.newPostPolicy() | -| `callback(err, {postURL, formData})` | _function_ | Callback function is called with non `null` err value in case of error. `postURL` will be the URL using which the object can be uploaded using POST request. `formData` is the object having key/value pairs for the Form data of POST body. If no callback is passed, a `Promise` is returned. | +In the expression `newPostPolicy expirationTime conditions` the parameters are: +| Param | Type | Description | +|:-----------------|:--------------------------------------------------|:---------------------------------------------| +| `expirationTime` | _UTCTime_ (from package `time:Data.Time.UTCTime`) | The expiration time for the policy | +| `conditions` | _[PostPolicyConditions]_ | List of conditions to be added to the policy | -Create policy: +The policy conditions are created using various helper functions - +please refer to the Haddocks for details. +Since conditions are validated by `newPostPolicy` it returns an +`Either` value. -```js -var policy = minioClient.newPostPolicy() -``` - -Apply upload policy restrictions: - -```js -// Policy restricted only for bucket 'mybucket'. -policy.setBucket('mybucket') - -// Policy restricted only for hello.txt object. -policy.setKey('hello.txt') -``` -or - -```js -// 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') - -// Set content disposition response header. -policy.setContentDisposition('attachment; filename=text.txt') - -// Only allow content size in range 1KB to 1MB. -policy.setContentLengthRange(1024, 1024*1024) - -// Set key-value user defined metadata -policy.setUserMetaData({ - key: 'value' -}) -``` - -POST your content from the browser using `superagent`: - - -```js -minioClient.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__ - - - -| Param | Type | Description | -|-------------------------------------------|------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| `bucketName` | _string_ | Name of the bucket. | -| `callback(err, bucketNotificationConfig)` | _function_ | Callback function is called with non `null` err value in case of error. `bucketNotificationConfig` will be the object that carries all notification configurations associated to bucketName. If no callback is passed, a `Promise` is returned. | +__Return Value__ +`presignedPostPolicy` returns a 2-tuple - the generated URL and a map +containing the form-data that should be submitted with the request. __Example__ +```haskell +{-# Language OverloadedStrings #-} -```js -minioClient.getBucketNotification('mybucket', function(err, bucketNotificationConfig) { - if (err) return console.log(err) - console.log(bucketNotificationConfig) -}) +import Network.Minio + +import qualified Data.ByteString as B +import qualified Data.ByteString.Char8 as Char8 +import qualified Data.HashMap.Strict as H +import qualified Data.Text.Encoding as Enc +import qualified Data.Time as Time + +main :: IO () +main = do + now <- Time.getCurrentTime + let + bucket = "mybucket" + object = "myobject" + + -- set an expiration time of 10 days + expireTime = Time.addUTCTime (3600 * 24 * 10) now + + -- create a policy with expiration time and conditions - since the + -- conditions are validated, newPostPolicy returns an Either value + policyE = newPostPolicy expireTime + [ -- set the object name condition + ppCondKey "photos/my-object" + -- set the bucket name condition + , ppCondBucket "my-bucket" + -- set the size range of object as 1B to 10MiB + , ppCondContentLengthRange 1 (10*1024*1024) + -- set content type as jpg image + , ppCondContentType "image/jpeg" + -- on success set the server response code to 200 + , ppCondSuccessActionStatus 200 + ] + + case policyE of + Left err -> putStrLn $ show err + Right policy -> do + res <- runMinio minioPlayCI $ do + (url, formData) <- presignedPostPolicy policy + + -- a curl command is output to demonstrate using the generated + -- URL and form-data + let + formFn (k, v) = B.concat ["-F ", Enc.encodeUtf8 k, "=", + "'", v, "'"] + formOptions = B.intercalate " " $ map formFn $ H.toList formData + + + return $ B.intercalate " " $ + ["curl", formOptions, "-F file=@/tmp/photo.jpg", url] + + case res of + Left e -> putStrLn $ "post-policy error: " ++ (show e) + Right cmd -> do + putStrLn $ "Put a photo at /tmp/photo.jpg and run command:\n" + + -- print the generated curl command + Char8.putStrLn cmd ``` - -### setBucketNotification(bucketName, bucketNotificationConfig[, callback]) + -Upload a user-created notification configuration and associate it to the specified bucket name. + + -__Parameters__ - - -| Param | Type | Description | -|----------------------------|----------------------|----------------------------------------------------------------------------------------------------------------------------| -| `bucketName` | _string_ | Name of the bucket. | -| `bucketNotificationConfig` | _BucketNotification_ | Javascript object that carries the notification configuration. | -| `callback(err)` | _function_ | Callback function is called with non `null` err value in case of error. If no callback is passed, a `Promise` is returned. | - - -__Example__ - -```js -// Create a new notification object -var bucketNotification = new Minio.NotificationConfig(); - -// Setup a new Queue configuration -var arn = Minio.buildARN('aws', 'sqs', 'us-west-2', '1', 'webhook') -var queue = new Minio.QueueConfig(arn) -queue.addFilterSuffix('.jpg') -queue.addFilterPrefix('myphotos/') -queue.addEvent(Minio.ObjectReducedRedundancyLostObject) -queue.addEvent(Minio.ObjectCreatedAll) - -// Add the queue to the overall notification object -bucketNotification.add(queue) - -minioClient.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__ - - -| Param | Type | Description | -|-----------------|------------|----------------------------------------------------------------------------------------------------------------------------| -| `bucketName` | _string_ | Name of the bucket | -| `callback(err)` | _function_ | Callback function is called with non `null` err value in case of error. If no callback is passed, a `Promise` is returned. | - - -```js -minioClient.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 registered 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__ - -| Param | Type | Description | -|--------------|----------|-------------------------------------------------| -| `bucketName` | _string_ | Name of the bucket | -| `prefix` | _string_ | Object key prefix to filter notifications for. | -| `suffix` | _string_ | Object key suffix to filter notifications for. | -| `events` | _Array_ | Enables notifications for specific event types. | - -See [here](https://github.com/minio/minio-js/blob/master/examples/minio/listen-bucket-notification.js) for a full example. - -```js -var listener = minioClient.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__ - - -| Param | Type | Description | -|-------------------------|------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| `bucketName` | _string_ | Name of the bucket | -| `callback(err, policy)` | _function_ | Callback function is called with non `null` err value in case of error. `policy` is [bucket policy](https://docs.aws.amazon.com/AmazonS3/latest/dev/example-bucket-policies.html). If no callback is passed, a `Promise` is returned. | - - -```js -// Retrieve bucket policy of 'my-bucketname' -minioClient.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](https://docs.aws.amazon.com/AmazonS3/latest/dev/example-bucket-policies.html) is detailed here. - -__Parameters__ - - -| Param | Type | Description | -|-----------------|------------|----------------------------------------------------------------------------------------------------------------------------| -| `bucketName` | _string_ | Name of the bucket. | -| `bucketPolicy` | _string_ | bucket policy. | -| `callback(err)` | _function_ | Callback function is called with non `null` err value in case of error. If no callback is passed, a `Promise` is returned. | - - -```js -// Set the bucket policy of `my-bucketname` -minioClient.setBucketPolicy('my-bucketname', JSON.stringify(policy), function(err) { - if (err) throw err - - console.log('Bucket policy set') -}) -``` -## 6. Custom Settings - - -### setS3TransferAccelerate(endpoint) -Set AWS S3 transfer acceleration endpoint for all API requests hereafter. -NOTE: This API applies only to AWS S3 and is a no operation for S3 compatible object storage services. - -__Parameters__ - -| Param | Type | Description | -|------------|----------|-----------------------------------------------| -| `endpoint` | _string_ | Set to new S3 transfer acceleration endpoint. | - - -## 7. HTTP request options -### setRequestOptions(options) - -Set the HTTP/HTTPS request options. Supported options are `agent` ([http.Agent()](https://nodejs.org/api/http.html#http_class_http_agent)), `family` ([IP address family to use while resolving `host` or `hostname`](https://nodejs.org/api/http.html#http_http_request_url_options_callback)), and tls related options ('agent', 'ca', 'cert', 'ciphers', 'clientCertEngine', 'crl', 'dhparam', 'ecdhCurve', 'honorCipherOrder', 'key', 'passphrase', 'pfx', 'rejectUnauthorized', 'secureOptions', 'secureProtocol', 'servername', 'sessionIdContext') documented [here](https://nodejs.org/api/tls.html#tls_tls_createsecurecontext_options) - -```js -// Do not reject self signed certificates. -minioClient.setRequestOptions({rejectUnauthorized: false}) -``` - - -## 7. Explore Further - -- [Build your own Shopping App Example](https://github.com/minio/minio-js-store-app) + diff --git a/source/developers/haskell/quickstart.md b/source/developers/haskell/quickstart.md index bebedc7e..a2115f17 100644 --- a/source/developers/haskell/quickstart.md +++ b/source/developers/haskell/quickstart.md @@ -1,248 +1,177 @@ -# MinIO JavaScript Library for Amazon S3 Compatible Cloud Storage [![Slack](https://slack.min.io/slack?type=svg)](https://slack.min.io) +# MinIO Client SDK for Haskell [![Build Status](https://travis-ci.org/minio/minio-hs.svg?branch=master)](https://travis-ci.org/minio/minio-hs)[![Hackage](https://img.shields.io/hackage/v/minio-hs.svg)](https://hackage.haskell.org/package/minio-hs)[![Slack](https://slack.min.io/slack?type=svg)](https://slack.min.io) -[![NPM](https://nodei.co/npm/minio.png)](https://nodei.co/npm/minio/) +The MinIO Haskell Client SDK provides simple APIs to access [MinIO](https://min.io) and Amazon S3 compatible object storage server. -The MinIO JavaScript Client SDK provides simple APIs to access any Amazon S3 compatible object storage server. +## Minimum Requirements -This quickstart guide will show you how to install the client SDK and execute an example JavaScript program. For a complete list of APIs and examples, please take a look at the [JavaScript Client API Reference](https://docs.min.io/docs/javascript-client-api-reference) documentation. +- The Haskell [stack](https://docs.haskellstack.org/en/stable/README/) -This document assumes that you have a working [nodejs](http://nodejs.org/) setup in place. +## Installation +### Add to your project -## Download from NPM +Simply add `minio-hs` to your project's `.cabal` dependencies section or if you are using hpack, to your `package.yaml` file as usual. + +### Try it out directly with `ghci` + +From your home folder or any non-haskell project directory, just run: ```sh -npm install --save minio + +stack install minio-hs + ``` -## Download from Source +Then start an interpreter session and browse the available APIs with: ```sh -git clone https://github.com/minio/minio-js -cd minio-js -npm install -npm install -g + +$ stack ghci +> :browse Network.Minio ``` -## Using with TypeScript +## Examples -```sh -npm install --save-dev @types/minio +The [examples](https://github.com/minio/minio-hs/tree/master/examples) folder contains many examples that you can try out and use to learn and to help with developing your own projects. + +### Quick-Start Example - File Uploader + +This example program connects to a MinIO object storage server, makes a bucket on the server and then uploads a file to the bucket. + +We will use the MinIO server running at https://play.min.io in this example. Feel free to use this service for testing and development. Access credentials are present in the library and are open to the public. + +### FileUploader.hs +``` haskell +#!/usr/bin/env stack +-- stack --resolver lts-14.11 runghc --package minio-hs --package optparse-applicative --package filepath + +-- +-- MinIO Haskell SDK, (C) 2017-2019 MinIO, Inc. +-- +-- Licensed under the Apache License, Version 2.0 (the "License"); +-- you may not use this file except in compliance with the License. +-- You may obtain a copy of the License at +-- +-- http://www.apache.org/licenses/LICENSE-2.0 +-- +-- Unless required by applicable law or agreed to in writing, software +-- distributed under the License is distributed on an "AS IS" BASIS, +-- WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +-- See the License for the specific language governing permissions and +-- limitations under the License. +-- + + +{-# LANGUAGE OverloadedStrings #-} +{-# LANGUAGE ScopedTypeVariables #-} +import Network.Minio + +import Data.Monoid ((<>)) +import Data.Text (pack) +import Options.Applicative +import System.FilePath.Posix +import UnliftIO (throwIO, try) + +import Prelude + +-- | The following example uses minio's play server at +-- https://play.min.io. The endpoint and associated +-- credentials are provided via the libary constant, +-- +-- > minioPlayCI :: ConnectInfo +-- + +-- optparse-applicative package based command-line parsing. +fileNameArgs :: Parser FilePath +fileNameArgs = strArgument + (metavar "FILENAME" + <> help "Name of file to upload to AWS S3 or a MinIO server") + +cmdParser = info + (helper <*> fileNameArgs) + (fullDesc + <> progDesc "FileUploader" + <> header + "FileUploader - a simple file-uploader program using minio-hs") + +main :: IO () +main = do + let bucket = "my-bucket" + + -- Parse command line argument + filepath <- execParser cmdParser + let object = pack $ takeBaseName filepath + + res <- runMinio minioPlayCI $ do + -- Make a bucket; catch bucket already exists exception if thrown. + bErr <- try $ makeBucket bucket Nothing + + -- If the bucket already exists, we would get a specific + -- `ServiceErr` exception thrown. + case bErr of + Left BucketAlreadyOwnedByYou -> return () + Left e -> throwIO e + Right _ -> return () + + -- Upload filepath to bucket; object name is derived from filepath. + fPutObject bucket object filepath defaultPutObjectOptions + + case res of + Left e -> putStrLn $ "file upload failed due to " ++ show e + Right () -> putStrLn "file upload succeeded." ``` -## Initialize MinIO Client +### Run FileUploader -You need five items in order to connect to MinIO object storage server. +``` sh +./FileUploader.hs "path/to/my/file" - -| Params | Description | -| :------- | :------------ | -| endPoint | URL to object storage service. | -|port| TCP/IP port number. This input is optional. Default value set to ``80`` for HTTP and ``443`` for HTTPs.| -| accessKey | Access key is like user ID that uniquely identifies your account. | -| secretKey | Secret key is the password to your account. | -|useSSL |Set this value to 'true' to enable secure (HTTPS) access | - - -```js -var Minio = require('minio') - -var minioClient = new Minio.Client({ - endPoint: 'play.min.io', - port: 9000, - useSSL: true, - accessKey: 'Q3AM3UQ867SPQQA43P2F', - secretKey: 'zuf+tfteSlswRu7BJ86wekitnifILbZam1KYY3TG' -}); ``` -## Quick Start Example - File Uploader - -This example program connects to an object storage server, makes a bucket on the server and then uploads a file to the bucket. - -We will use the MinIO server running at [https://play.min.io](https://play.min.io) in this example. Feel free to use this service for testing and development. Access credentials shown in this example are open to the public. - -#### file-uploader.js - -```js -var Minio = require('minio') - -// Instantiate the minio client with the endpoint -// and access keys as shown below. -var minioClient = new Minio.Client({ - endPoint: 'play.min.io', - port: 9000, - useSSL: true, - accessKey: 'Q3AM3UQ867SPQQA43P2F', - secretKey: 'zuf+tfteSlswRu7BJ86wekitnifILbZam1KYY3TG' -}); - -// File that needs to be uploaded. -var file = '/tmp/photos-europe.tar' - -// Make a bucket called europetrip. -minioClient.makeBucket('europetrip', 'us-east-1', function(err) { - if (err) return console.log(err) - - console.log('Bucket created successfully in "us-east-1".') - - var metaData = { - 'Content-Type': 'application/octet-stream', - 'X-Amz-Meta-Testing': 1234, - 'example': 5678 - } - // Using fPutObject API upload your file to the bucket europetrip. - minioClient.fPutObject('europetrip', 'photos-europe.tar', file, metaData, function(err, etag) { - if (err) return console.log(err) - console.log('File uploaded successfully.') - }); -}); -``` - -#### Run file-uploader - -```sh -node file-uploader.js -Bucket created successfully in "us-east-1". - -mc ls play/europetrip/ -[2016-05-25 23:49:50 PDT] 17MiB photos-europe.tar -``` - -## API Reference - -The full API Reference is available here. - -* [Complete API Reference](https://docs.min.io/docs/javascript-client-api-reference) - -### API Reference : Bucket Operations - -* [`makeBucket`](https://docs.min.io/docs/javascript-client-api-reference#makeBucket) -* [`listBuckets`](https://docs.min.io/docs/javascript-client-api-reference#listBuckets) -* [`bucketExists`](https://docs.min.io/docs/javascript-client-api-reference#bucketExists) -* [`removeBucket`](https://docs.min.io/docs/javascript-client-api-reference#removeBucket) -* [`listObjects`](https://docs.min.io/docs/javascript-client-api-reference#listObjects) -* [`listObjectsV2`](https://docs.min.io/docs/javascript-client-api-reference#listObjectsV2) -* [`listObjectsV2WithMetadata`](https://docs.min.io/docs/javascript-client-api-reference#listObjectsV2WithMetadata) (Extension) -* [`listIncompleteUploads`](https://docs.min.io/docs/javascript-client-api-reference#listIncompleteUploads) -* [`getBucketVersioning`](https://docs.min.io/docs/javascript-client-api-reference#getBucketVersioning) -* [`setBucketVersioning`](https://docs.min.io/docs/javascript-client-api-reference#setBucketVersioning) -* [`setBucketLifecycle`](https://docs.min.io/docs/javascript-client-api-reference#setBucketLifecycle) -* [`getBucketLifecycle`](https://docs.min.io/docs/javascript-client-api-reference#getBucketLifecycle) -* [`removeBucketLifecycle`](https://docs.min.io/docs/javascript-client-api-reference#removeBucketLifecycle) -* [`getObjectLockConfig`](https://docs.min.io/docs/javascript-client-api-reference#getObjectLockConfig) -* [`setObjectLockConfig`](https://docs.min.io/docs/javascript-client-api-reference#setObjectLockConfig) - -### API Reference : File Object Operations - -* [`fPutObject`](https://docs.min.io/docs/javascript-client-api-reference#fPutObject) -* [`fGetObject`](https://docs.min.io/docs/javascript-client-api-reference#fGetObject) - -### API Reference : Object Operations - -* [`getObject`](https://docs.min.io/docs/javascript-client-api-reference#getObject) -* [`putObject`](https://docs.min.io/docs/javascript-client-api-reference#putObject) -* [`copyObject`](https://docs.min.io/docs/javascript-client-api-reference#copyObject) -* [`statObject`](https://docs.min.io/docs/javascript-client-api-reference#statObject) -* [`removeObject`](https://docs.min.io/docs/javascript-client-api-reference#removeObject) -* [`removeObjects`](https://docs.min.io/docs/javascript-client-api-reference#removeObjects) -* [`removeIncompleteUpload`](https://docs.min.io/docs/javascript-client-api-reference#removeIncompleteUpload) -* [`selectObjectContent`](https://docs.min.io/docs/javascript-client-api-reference#selectObjectContent) - - -### API Reference : Presigned Operations - -* [`presignedGetObject`](https://docs.min.io/docs/javascript-client-api-reference#presignedGetObject) -* [`presignedPutObject`](https://docs.min.io/docs/javascript-client-api-reference#presignedPutObject) -* [`presignedPostPolicy`](https://docs.min.io/docs/javascript-client-api-reference#presignedPostPolicy) - -### API Reference : Bucket Notification Operations - -* [`getBucketNotification`](https://docs.min.io/docs/javascript-client-api-reference#getBucketNotification) -* [`setBucketNotification`](https://docs.min.io/docs/javascript-client-api-reference#setBucketNotification) -* [`removeAllBucketNotification`](https://docs.min.io/docs/javascript-client-api-reference#removeAllBucketNotification) -* [`listenBucketNotification`](https://docs.min.io/docs/javascript-client-api-reference#listenBucketNotification) (MinIO Extension) - -### API Reference : Bucket Policy Operations - -* [`getBucketPolicy`](https://docs.min.io/docs/javascript-client-api-reference#getBucketPolicy) -* [`setBucketPolicy`](https://docs.min.io/docs/javascript-client-api-reference#setBucketPolicy) - - -## Full Examples - -#### Full Examples : Bucket Operations - -* [list-buckets.js](https://github.com/minio/minio-js/blob/master/examples/list-buckets.js) -* [list-objects.js](https://github.com/minio/minio-js/blob/master/examples/list-objects.js) -* [list-objects-v2.js](https://github.com/minio/minio-js/blob/master/examples/list-objects-v2.js) -* [list-objects-v2-with-metadata.js](https://github.com/minio/minio-js/blob/master/examples/list-objects-v2-with-metadata.js) (Extension) -* [bucket-exists.js](https://github.com/minio/minio-js/blob/master/examples/bucket-exists.js) -* [make-bucket.js](https://github.com/minio/minio-js/blob/master/examples/make-bucket.js) -* [remove-bucket.js](https://github.com/minio/minio-js/blob/master/examples/remove-bucket.js) -* [list-incomplete-uploads.js](https://github.com/minio/minio-js/blob/master/examples/list-incomplete-uploads.js) -* [get-bucket-versioning.js](https://github.com/minio/minio-js/blob/master/examples/get-bucket-versioning.js) -* [set-bucket-versioning.js](https://github.com/minio/minio-js/blob/master/examples/set-bucket-versioning.js) -* [set-bucket-tagging.js](https://github.com/minio/minio-js/blob/master/examples/set-bucket-tagging.js) -* [get-bucket-tagging.js](https://github.com/minio/minio-js/blob/master/examples/get-bucket-tagging.js) -* [remove-bucket-tagging.js](https://github.com/minio/minio-js/blob/master/examples/remove-bucket-tagging.js) -* [set-bucket-lifecycle.js](https://github.com/minio/minio-js/blob/master/examples/set-bucket-lifecycle.js) -* [get-bucket-lifecycle.js](https://github.com/minio/minio-js/blob/master/examples/get-bucket-lifecycle.js) -* [remove-bucket-lifecycle.js](https://github.com/minio/minio-js/blob/master/examples/remove-bucket-lifecycle.js) -* [get-object-lock-config.js](https://github.com/minio/minio-js/blob/master/examples/get-object-lock-config.js) -* [set-object-lock-config.js](https://github.com/minio/minio-js/blob/master/examples/set-object-lock-config.js) -* [set-bucket-replication.js](https://github.com/minio/minio-js/blob/master/examples/set-bucket-replication.js) -* [get-bucket-replication.js](https://github.com/minio/minio-js/blob/master/examples/get-bucket-replication.js) -* [remove-bucket-replication.js](https://github.com/minio/minio-js/blob/master/examples/remove-bucket-replication.js) - -#### Full Examples : File Object Operations -* [fput-object.js](https://github.com/minio/minio-js/blob/master/examples/fput-object.js) -* [fget-object.js](https://github.com/minio/minio-js/blob/master/examples/fget-object.js) - -#### Full Examples : Object Operations -* [put-object.js](https://github.com/minio/minio-js/blob/master/examples/put-object.js) -* [get-object.js](https://github.com/minio/minio-js/blob/master/examples/get-object.js) -* [copy-object.js](https://github.com/minio/minio-js/blob/master/examples/copy-object.js) -* [get-partialobject.js](https://github.com/minio/minio-js/blob/master/examples/get-partialobject.js) -* [remove-object.js](https://github.com/minio/minio-js/blob/master/examples/remove-object.js) -* [remove-incomplete-upload.js](https://github.com/minio/minio-js/blob/master/examples/remove-incomplete-upload.js) -* [stat-object.js](https://github.com/minio/minio-js/blob/master/examples/stat-object.js) -* [get-object-retention.js](https://github.com/minio/minio-js/blob/master/examples/get-object-retention.js) -* [put-object-retention.js](https://github.com/minio/minio-js/blob/master/examples/put-object-retention.js) -* [put-object-tagging.js](https://github.com/minio/minio-js/blob/master/examples/put-object-tagging.js) -* [get-object-tagging.js](https://github.com/minio/minio-js/blob/master/examples/get-object-tagging.js) -* [remove-object-tagging.js](https://github.com/minio/minio-js/blob/master/examples/remove-object-tagging.js) -* [set-object-legal-hold.js](https://github.com/minio/minio-js/blob/master/examples/set-object-legalhold.js) -* [get-object-legal-hold.js](https://github.com/minio/minio-js/blob/master/examples/get-object-legal-hold.js) -* [compose-object.js](https://github.com/minio/minio-js/blob/master/examples/compose-object.js) -* [select-object-content.js](https://github.com/minio/minio-js/blob/master/examples/select-object-content.js) - -#### Full Examples : Presigned Operations -* [presigned-getobject.js](https://github.com/minio/minio-js/blob/master/examples/presigned-getobject.js) -* [presigned-putobject.js](https://github.com/minio/minio-js/blob/master/examples/presigned-putobject.js) -* [presigned-postpolicy.js](https://github.com/minio/minio-js/blob/master/examples/presigned-postpolicy.js) - -#### Full Examples: Bucket Notification Operations -* [get-bucket-notification.js](https://github.com/minio/minio-js/blob/master/examples/get-bucket-notification.js) -* [set-bucket-notification.js](https://github.com/minio/minio-js/blob/master/examples/set-bucket-notification.js) -* [remove-all-bucket-notification.js](https://github.com/minio/minio-js/blob/master/examples/remove-all-bucket-notification.js) -* [listen-bucket-notification.js](https://github.com/minio/minio-js/blob/master/examples/minio/listen-bucket-notification.js) (MinIO Extension) - -#### Full Examples: Bucket Policy Operations -* [get-bucket-policy.js](https://github.com/minio/minio-js/blob/master/examples/get-bucket-policy.js) -* [set-bucket-policy.js](https://github.com/minio/minio-js/blob/master/examples/set-bucket-policy.js) - -## Custom Settings -* [setAccelerateEndPoint](https://github.com/minio/minio-js/blob/master/examples/set-accelerate-end-point.js) - -## Explore Further -* [Complete Documentation](https://docs.min.io) -* [MinIO JavaScript Client SDK API Reference](https://docs.min.io/docs/javascript-client-api-reference) -* [Build your own Shopping App Example- Full Application Example ](https://github.com/minio/minio-js-store-app) - ## Contribute -[Contributors Guide](https://github.com/minio/minio-js/blob/master/CONTRIBUTING.md) +[Contributors Guide](https://github.com/minio/minio-hs/blob/master/CONTRIBUTING.md) -[![Build Status](https://travis-ci.org/minio/minio-js.svg)](https://travis-ci.org/minio/minio-js) -[![Build status](https://ci.appveyor.com/api/projects/status/1d05e6nvxcelmrak?svg=true)](https://ci.appveyor.com/project/harshavardhana/minio-js) +### Development + +To setup: + +```sh +git clone https://github.com/minio/minio-hs.git + +cd minio-hs/ + +stack install +``` + +Tests can be run with: + +```sh + +stack test + +``` + +A section of the tests use the remote MinIO Play server at `https://play.min.io` by default. For library development, using this remote server maybe slow. To run the tests against a locally running MinIO live server at `http://localhost:9000`, just set the environment `MINIO_LOCAL` to any value (and unset it to switch back to Play). + +To run the live server tests, set a build flag as shown below: + +```sh + +stack test --flag minio-hs:live-test + +# OR against a local MinIO server with: + +MINIO_LOCAL=1 stack test --flag minio-hs:live-test + +``` + +The configured CI system always runs both test-suites for every change. + +Documentation can be locally built with: + +```sh + +stack haddock + +``` diff --git a/source/developers/javascript/API.md b/source/developers/javascript/API.md index 25ad48e1..d64ed38f 100644 --- a/source/developers/javascript/API.md +++ b/source/developers/javascript/API.md @@ -1,1030 +1,2149 @@ -# MinIO Haskell SDK API Reference +# JavaScript Client API Reference [![Slack](https://slack.min.io/slack?type=svg)](https://slack.min.io) ## Initialize MinIO Client object. -### MinIO - for public Play server +## MinIO -```haskell -minioPlayCI :: ConnectInfo -minioPlayCI +```js +var Minio = require('minio') +var minioClient = new Minio.Client({ + endPoint: 'play.min.io', + port: 9000, + useSSL: true, + accessKey: 'Q3AM3UQ867SPQQA43P2F', + secretKey: 'zuf+tfteSlswRu7BJ86wekitnifILbZam1KYY3TG' +}); ``` -### AWS S3 +## AWS S3 -```haskell -awsCI :: ConnectInfo -awsCI { connectAccesskey = "your-access-key" - , connectSecretkey = "your-secret-key" - } +```js +var Minio = require('minio') +var s3Client = new Minio.Client({ + endPoint: 's3.amazonaws.com', + accessKey: 'YOUR-ACCESSKEYID', + secretKey: 'YOUR-SECRETACCESSKEY' +}) ``` -| Bucket operations | Object Operations | Presigned Operations | -|:--------------------------------------------------|:----------------------------------------------|:--------------------------------------------------| -| [`listBuckets`](#listBuckets) | [`getObject`](#getObject) | [`presignedGetObjectUrl`](#presignedGetObjectUrl) | -| [`makeBucket`](#makeBucket) | [`putObject`](#putObject) | [`presignedPutObjectUrl`](#presignedPutObjectUrl) | -| [`removeBucket`](#removeBucket) | [`fGetObject`](#fGetObject) | [`presignedPostPolicy`](#presignedPostPolicy) | -| [`listObjects`](#listObjects) | [`fPutObject`](#fPutObject) | | -| [`listObjectsV1`](#listObjectsV1) | [`copyObject`](#copyObject) | | -| [`listIncompleteUploads`](#listIncompleteUploads) | [`removeObject`](#removeObject) | | -| [`bucketExists`](#bucketExists) | [`selectObjectContent`](#selectObjectContent) | | +| Bucket operations | Object operations | Presigned operations | Bucket Policy & Notification operations | Custom Settings | | +|-------------------------------------------------------|-----------------------------------------------------|-----------------------------------------------|---------------------------------------------------------------|-------------------------------------------------------|-----| +| [`makeBucket`](#makeBucket) | [`getObject`](#getObject) | [`presignedUrl`](#presignedUrl) | [`getBucketNotification`](#getBucketNotification) | [`setS3TransferAccelerate`](#setS3TransferAccelerate) | | +| [`listBuckets`](#listBuckets) | [`getPartialObject`](#getPartialObject) | [`presignedGetObject`](#presignedGetObject) | [`setBucketNotification`](#setBucketNotification) | | | +| [`bucketExists`](#bucketExists) | [`fGetObject`](#fGetObject) | [`presignedPutObject`](#presignedPutObject) | [`removeAllBucketNotification`](#removeAllBucketNotification) | | | +| [`removeBucket`](#removeBucket) | [`putObject`](#putObject) | [`presignedPostPolicy`](#presignedPostPolicy) | [`getBucketPolicy`](#getBucketPolicy) | | | +| [`listObjects`](#listObjects) | [`fPutObject`](#fPutObject) | | [`setBucketPolicy`](#setBucketPolicy) | | | +| [`listObjectsV2`](#listObjectsV2) | [`copyObject`](#copyObject) | | [`listenBucketNotification`](#listenBucketNotification) | | | +| [`listIncompleteUploads`](#listIncompleteUploads) | [`statObject`](#statObject) | | | | | +| [`getBucketVersioning`](#getBucketVersioning) | [`removeObject`](#removeObject) | | | | | +| [`setBucketVersioning`](#setBucketVersioning) | [`removeObjects`](#removeObjects) | | | | | +| [`getBucketTagging`](#getBucketTagging) | [`removeIncompleteUpload`](#removeIncompleteUpload) | | | | | +| [`setBucketTagging`](#setBucketTagging) | [`putObjectRetention`](#putObjectRetention) | | | | | +| [`removeBucketTagging`](#removeBucketTagging) | [`getObjectRetention`](#getObjectRetention) | | | | | +| [`setBucketLifecycle`](#setBucketLifecycle) | [`putObjectTagging`](#putObjectTagging) | | | | | +| [`getBucketLifecycle`](#getBucketLifecycle) | [`removeObjectTagging`](#removeObjectTagging) | | | | | +| [`removeBucketLifecycle`](#removeBucketLifecycle) | [`getObjectTagging`](#getObjectTagging) | | | | | +| [`setObjectLockConfig`](#setObjectLockConfig) | [`getObjectLegalHold`](#getObjectLegalHold) | | | | | +| [`getObjectLockConfig`](#getObjectLockConfig) | [`setObjectLegalHold`](#setObjectLegalHold) | | | | | +| [`getBucketEncryption`](#getBucketEncryption) | [`composeObject`](#composeObject) | | | | | +| [`setBucketEncryption`](#setBucketEncryption) | [`selectObjectContent`](#selectObjectContent) | | | | | +| [`removeBucketEncryption`](#removeBucketEncryption) | | | | | | +| [`setBucketReplication`](#setBucketReplication) | | | | | | +| [`getBucketReplication`](#getBucketReplication) | | | | | | +| [`removeBucketReplication`](#removeBucketReplication) | | | | | | +## 1. Constructor -## 1. Connecting and running operations on the storage service + +### new Minio.Client ({endPoint, port, useSSL, accessKey, secretKey, region, transport, sessionToken, partSize}) -The Haskell MinIO SDK provides high-level functionality to perform -operations on a MinIO server or any AWS S3-like API compatible storage -service. +| | +| ---- | +|``new Minio.Client ({endPoint, port, useSSL, accessKey, secretKey, region, transport, sessionToken, partSize})``| +|Initializes a new client object.| -### The `ConnectInfo` type +__Parameters__ -The `ConnectInfo` record-type contains connection information for a -particular server. It is recommended to construct the `ConnectInfo` -value using one of the several smart constructors provided by the -library, documented in the following subsections. +| Param | Type | Description | +|----------------|----------|--------------------------------------------------------------------------------------------------------------| +| `endPoint` | _string_ | endPoint is a host name or an IP address. | +| `port` | _number_ | TCP/IP port number. This input is optional. Default value set to 80 for HTTP and 443 for HTTPs. | +| `useSSL` | _bool_ | If set to true, https is used instead of http. Default is true. | +| `accessKey` | _string_ | accessKey is like user-id that uniquely identifies your account. | +| `secretKey` | _string_ | secretKey is the password to your account. | +| `sessionToken` | _string_ | Set this value to provide x-amz-security-token (AWS S3 specific). (Optional) | +| `region` | _string_ | Set this value to override region cache. (Optional) | +| `transport` | _string_ | Set this value to pass in a custom transport. (Optional) | +| `partSize` | _number_ | Set this value to override default part size of 64MB for multipart uploads. (Optional) | +| `pathStyle` | _bool_ | Set this value to override default access behavior (path) for non AWS endpoints. Default is true. (Optional) | -The library automatically discovers the region of a bucket by -default. This is especially useful with AWS, where buckets may be in -different regions. When performing an upload, download or other -operation, the library requests the service for the location of a -bucket and caches it for subsequent requests. +__Example__ -#### awsCI :: ConnectInfo +## Create client for MinIO -`awsCI` is a value that provides connection information for AWS -S3. Credentials can be supplied by overriding a couple of fields like -so: +```js +var Minio = require('minio') -``` haskell -awsConn = awsCI { - connectAccessKey = "my-AWS-access-key" - , connectSecretKey = "my-AWS-secret-key" - } +var minioClient = new Minio.Client({ + endPoint: 'play.min.io', + port: 9000, + useSSL: true, + accessKey: 'Q3AM3UQ867SPQQA43P2F', + secretKey: 'zuf+tfteSlswRu7BJ86wekitnifILbZam1KYY3TG' +}); ``` -#### awsWithRegionCI :: Region -> Bool -> ConnectInfo +## Create client for AWS S3 -This constructor allows to specify the initial region and a Boolean to -enable/disable the automatic region discovery behaviour. +```js +var Minio = require('minio') -The parameters in the expression `awsWithRegion region autoDiscover` are: - -| Parameter | Type | Description | -|:---------------|:----------------------------|:---------------------------------------------------------------------------------------------------------------------------| -| `region` | _Region_ (alias for `Text`) | The region to connect to by default for all requests. | -| `autoDiscover` | _Bool_ | If `True`, region discovery will be enabled. If `False`, discovery is disabled, and all requests go the given region only. | - -#### minioPlayCI :: ConnectInfo - -This constructor provides connection and authentication information to -connect to the public MinIO Play server at -`https://play.min.io/`. - -#### minioCI :: Text -> Int -> Bool -> ConnectInfo - -Use to connect to a MinIO server. - -The parameters in the expression `minioCI host port isSecure` are: - -| Parameter | Type | Description | -|:-----------|:-------|:--------------------------------------------------------| -| `host` | _Text_ | Hostname of the MinIO or other S3-API compatible server | -| `port` | _Int_ | Port number to connect to | -| `isSecure` | _Bool_ | Does the server use HTTPS? | - -#### The ConnectInfo fields and Default instance - -The following table shows the fields in the `ConnectInfo` record-type: - -| Field | Type | Description | -|:----------------------------|:----------------------------|:--------------------------------------------------------------------------------------------------| -| `connectHost` | _Text_ | Host name of the server. Defaults to `localhost`. | -| `connectPort` | _Int_ | Port number on which the server listens. Defaults to `9000`. | -| `connectAccessKey` | _Text_ | Access key to use in authentication. Defaults to `minio`. | -| `connectSecretkey` | _Text_ | Secret key to use in authentication. Defaults to `minio123`. | -| `connectIsSecure` | _Bool_ | Specifies if the server used TLS. Defaults to `False` | -| `connectRegion` | _Region_ (alias for `Text`) | Specifies the region to use. Defaults to 'us-east-1' | -| `connectAutoDiscoverRegion` | _Bool_ | Specifies if the library should automatically discover the region of a bucket. Defaults to `True` | - -The `def` value of type `ConnectInfo` has all the above default -values. - -### The Minio Monad - -This monad provides the required environment to perform requests -against a MinIO or other S3 API compatible server. It uses the -connection information from the `ConnectInfo` value provided to it. It -performs connection pooling, bucket location caching, error handling -and resource clean-up actions. - -The `runMinio` function performs the provided action in the `Minio` -monad and returns a `IO (Either MinioErr a)` value: - -``` haskell -{-# Language OverloadedStrings #-} - -import Network.Minio - -main :: IO () -main = do - result <- runMinio def $ do - buckets <- listBuckets - return $ length buckets - - case result of - Left e -> putStrLn $ "Failed operation with error: " ++ show e - Right n -> putStrLn $ show n ++ " bucket(s) found." +var s3Client = new Minio.Client({ + endPoint: 's3.amazonaws.com', + accessKey: 'YOUR-ACCESSKEYID', + secretKey: 'YOUR-SECRETACCESSKEY' +}) ``` -The above performs a `listBuckets` operation and returns the number of -buckets in the server. If there were any errors, they will be returned -as values of type `MinioErr` as a `Left` value. +## Create client with temporary credentials + +```js +var Minio = require('minio') + +var s3Client = new Minio.Client({ + endPoint: 's3.amazonaws.com', + accessKey: 'YOUR-TEMP-ACCESSKEYID', + secretKey: 'YOUR-TEMP-SECRETACCESSKEY', + sessionToken: 'YOUR-TEMP-SESSIONTOKEN' +}) +``` ## 2. Bucket operations + + +### makeBucket(bucketName, region[, makeOpts , callback]) + +Creates a new bucket. + +__Parameters__ + +| Param | Type | Description | +|-----------------|------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `bucketName` | _string_ | Name of the bucket. | +| `region` | _string_ | Region where the bucket is created. This parameter is optional. Default value is us-east-1. | +| `makeOpts` | _object_ | Options to create a bucket. e.g `{ObjectLocking:true}` (Optional) | +| `callback(err)` | _function_ | Callback function with `err` as the error argument. `err` is null if the bucket is successfully created. If no callback is passed, a `Promise` is returned. | + +__Example__ + +```js +minioClient.makeBucket('mybucket', 'us-east-1', function(err) { + if (err) return console.log('Error creating bucket.', err) + console.log('Bucket created successfully in "us-east-1".') +}) +``` + +__Example 1__ +Create a bucket with object locking enabled. + +```js +minioClient.makeBucket('mybucket', 'us-east-1', { ObjectLocking:true }, function(err) { + if (err) return console.log('Error creating bucket with object lock.', err) + console.log('Bucket created successfully in "us-east-1" and enabled object lock') +}) +``` -### listBuckets :: Minio [BucketInfo] -Lists buckets. +### listBuckets([callback]) -__Return Value__ +Lists all buckets. -| Return type | Description | -|:---------------------|:----------------| -| _Minio [BucketInfo]_ | List of buckets | - - -__BucketInfo record type__ - -| Field | Type | Description | -|:-----------------|:---------------------------|:----------------------------| -| `biName` | _Bucket_ (alias of `Text`) | Name of the bucket | -| `biCreationDate` | _UTCTime_ | Creation time of the bucket | - - - -### makeBucket :: Bucket -> Maybe Region -> Minio () - -Create a new bucket. If the region is not specified, the region -specified by `ConnectInfo` is used. __Parameters__ -In the expression `makeBucket bucketName region` the arguments are: -| Param | Type | Description | -|--------------|-----------------------------|-----------------------------------------------------------------------------------------------------| -| `bucketName` | _Bucket_ (alias for `Text`) | Name of the bucket | -| `region` | _Maybe Region_ | Region where the bucket is to be created. If not specified, default to the region in `ConnectInfo`. | +| Param | Type | Description | +|---|---|---| +|`callback(err, bucketStream) ` | _function_ | Callback function with error as the first argument. `bucketStream` is the stream emitting bucket information. If no callback is passed, a `Promise` is returned. | -__Example__ +bucketStream emits Object with the format:- -``` haskell -{-# Language OverloadedStrings #-} +| Param | Type | Description | +|-----------------------|----------|-------------------------------| +| `bucket.name` | _string_ | bucket name | +| `bucket.creationDate` | _Date_ | date when bucket was created. | -main :: IO () -main = do - res <- runMinio minioPlayCI $ do - makeBucket bucketName (Just "us-east-1") - case res of - Left err -> putStrLn $ "Failed to make bucket: " ++ (show res) - Right _ -> putStrLn $ "makeBucket successful." - -``` - - -### removeBucket :: Bucket -> Minio () - -Remove a bucket. The bucket must be empty or an error will be thrown. - -__Parameters__ - -In the expression `removeBucket bucketName` the arguments are: - -| Param | Type | Description | -|--------------|-----------------------------|--------------------| -| `bucketName` | _Bucket_ (alias for `Text`) | Name of the bucket | __Example__ -``` haskell -{-# Language OverloadedStrings #-} - -main :: IO () -main = do - res <- runMinio minioPlayCI $ do - removeBucket "mybucket" - - case res of - Left err -> putStrLn $ "Failed to remove bucket: " ++ (show res) - Right _ -> putStrLn $ "removeBucket successful." - +```js +minioClient.listBuckets(function(err, buckets) { + if (err) return console.log(err) + console.log('buckets :', buckets) +}) ``` + +#### bucketExists(bucketName[, callback]) - -### listObjects :: Bucket -> Maybe Text -> Bool -> C.ConduitM () ObjectInfo Minio () - -List objects in the given bucket, implements version 2 of AWS S3 API. - -__Parameters__ - -In the expression `listObjects bucketName prefix recursive` the -arguments are: - -| Param | Type | Description | -|:-------------|:----------------------------|:---------------------------------------------------------------------------------------------------------| -| `bucketName` | _Bucket_ (alias for `Text`) | Name of the bucket | -| `prefix` | _Maybe Text_ | Optional prefix that listed objects should have | -| `recursive` | _Bool_ | `True` indicates recursive style listing and `False` indicates directory style listing delimited by '/'. | - -__Return Value__ - -| Return type | Description | -|:------------------------------------|:------------------------------------------------------------------------| -| _C.ConduitM () ObjectInfo Minio ()_ | A Conduit Producer of `ObjectInfo` values corresponding to each object. | - -__ObjectInfo record type__ - -| Field | Type | Description | -|:-------------|:----------------------------|:-------------------------------------| -| `oiObject` | _Object_ (alias for `Text`) | Name of object | -| `oiModTime` | _UTCTime_ | Last modified time of the object | -| `oiETag` | _ETag_ (alias for `Text`) | ETag of the object | -| `oiSize` | _Int64_ | Size of the object in bytes | -| `oiMetadata` | _HashMap Text Text_ | Map of key-value user-metadata pairs | - -__Example__ - -``` haskell -{-# LANGUAGE OverloadedStrings #-} -import Network.Minio - -import Conduit -import Prelude - - --- | The following example uses MinIO play server at --- https://play.min.io. The endpoint and associated --- credentials are provided via the libary constant, --- --- > minioPlayCI :: ConnectInfo --- - -main :: IO () -main = do - let - bucket = "test" - - -- Performs a recursive listing of all objects under bucket "test" - -- on play.min.io. - res <- runMinio minioPlayCI $ - runConduit $ listObjects bucket Nothing True .| mapM_C (\v -> (liftIO $ print v)) - print res -``` - - -### listObjectsV1 :: Bucket -> Maybe Text -> Bool -> C.ConduitM () ObjectInfo Minio () - -List objects in the given bucket, implements version 1 of AWS S3 API. This API -is provided for legacy S3 compatible object storage endpoints. - -__Parameters__ - -In the expression `listObjectsV1 bucketName prefix recursive` the -arguments are: - -| Param | Type | Description | -|:-------------|:----------------------------|:---------------------------------------------------------------------------------------------------------| -| `bucketName` | _Bucket_ (alias for `Text`) | Name of the bucket | -| `prefix` | _Maybe Text_ | Optional prefix that listed objects should have | -| `recursive` | _Bool_ | `True` indicates recursive style listing and `False` indicates directory style listing delimited by '/'. | - -__Return Value__ - -| Return type | Description | -|:------------------------------------|:------------------------------------------------------------------------| -| _C.ConduitM () ObjectInfo Minio ()_ | A Conduit Producer of `ObjectInfo` values corresponding to each object. | - -__ObjectInfo record type__ - -| Field | Type | Description | -|:------------|:----------------------------|:---------------------------------| -| `oiObject` | _Object_ (alias for `Text`) | Name of object | -| `oiModTime` | _UTCTime_ | Last modified time of the object | -| `oiETag` | _ETag_ (alias for `Text`) | ETag of the object | -| `oiSize` | _Int64_ | Size of the object in bytes | - -__Example__ - -``` haskell -{-# LANGUAGE OverloadedStrings #-} -import Network.Minio - -import Conduit -import Prelude - - --- | The following example uses MinIO play server at --- https://play.min.io. The endpoint and associated --- credentials are provided via the libary constant, --- --- > minioPlayCI :: ConnectInfo --- - -main :: IO () -main = do - let - bucket = "test" - - -- Performs a recursive listing of all objects under bucket "test" - -- on play.min.io. - res <- runMinio minioPlayCI $ - runConduit $ listObjectsV1 bucket Nothing True .| mapM_C (\v -> (liftIO $ print v)) - print res -``` - - -### listIncompleteUploads :: Bucket -> Maybe Prefix -> Bool -> C.Producer Minio UploadInfo - -List incompletely uploaded objects. - -__Parameters__ - -In the expression `listIncompleteUploads bucketName prefix recursive` -the parameters are: - -| Param | Type | Description | -|:-------------|:----------------------------|:---------------------------------------------------------------------------------------------------------| -| `bucketName` | _Bucket_ (alias for `Text`) | Name of the bucket | -| `prefix` | _Maybe Text_ | Optional prefix that listed objects should have. | -| `recursive` | _Bool_ | `True` indicates recursive style listing and `Talse` indicates directory style listing delimited by '/'. | - -__Return Value__ - -|Return type |Description | -|:---|:---| -| _C.ConduitM () UploadInfo Minio ()_ | A Conduit Producer of `UploadInfo` values corresponding to each incomplete multipart upload | - -__UploadInfo record type__ - -| Field | Type | Description | -|:-------------|:---------|:------------------------------------------| -| `uiKey` | _Object_ | Name of incompletely uploaded object | -| `uiUploadId` | _String_ | Upload ID of incompletely uploaded object | -| `uiSize` | _Int64_ | Size of incompletely uploaded object | - -__Example__ - -```haskell -{-# LANGUAGE OverloadedStrings #-} -import Network.Minio - -import Conduit -import Prelude - --- | The following example uses MinIO play server at --- https://play.min.io. The endpoint and associated --- credentials are provided via the libary constant, --- --- > minioPlayCI :: ConnectInfo --- - -main :: IO () -main = do - let - bucket = "test" - - -- Performs a recursive listing of incomplete uploads under bucket "test" - -- on a local MinIO server. - res <- runMinio minioPlayCI $ - runConduit $ listIncompleteUploads bucket Nothing True .| mapM_C (\v -> (liftIO $ print v)) - print res - -``` - -## 3. Object operations - - -### getObject :: Bucket -> Object -> GetObjectOptions -> Minio (C.ConduitM () ByteString Minio ()) - -Get an object from the S3 service, optionally object ranges can be provided as well. - -__Parameters__ - -In the expression `getObject bucketName objectName opts` the parameters -are: - -| Param | Type | Description | -|:-------------|:----------------------------|:----------------------------------------------------------------------------| -| `bucketName` | _Bucket_ (alias for `Text`) | Name of the bucket | -| `objectName` | _Object_ (alias for `Text`) | Name of the object | -| `opts` | _GetObjectOptions_ | Options for GET requests specifying additional options like If-Match, Range | - -__GetObjectOptions record type__ - -| Field | Type | Description | -|:-----------------------|:--------------------------------|:------------------------------------------------------------------------------------------------------| -| `gooRange` | `Maybe ByteRanges` | Represents the byte range of object. E.g ByteRangeFromTo 0 9 represents first ten bytes of the object | -| `gooIfMatch` | `Maybe ETag` (alias for `Text`) | (Optional) ETag of object should match | -| `gooIfNoneMatch` | `Maybe ETag` (alias for `Text`) | (Optional) ETag of object shouldn't match | -| `gooIfUnmodifiedSince` | `Maybe UTCTime` | (Optional) Time since object wasn't modified | -| `gooIfModifiedSince` | `Maybe UTCTime` | (Optional) Time since object was modified | - -__Return Value__ - -The return value can be incrementally read to process the contents of -the object. -| Return type | Description | -|:--------------------------------------------|:-----------------------------------------| -| _Minio (C.ConduitM () ByteString Minio ())_ | A Conduit source of `ByteString` values. | - -__Example__ - -```haskell -{-# LANGUAGE OverloadedStrings #-} -import Network.Minio - -import qualified Data.Conduit as C -import qualified Data.Conduit.Binary as CB - -import Prelude - --- | The following example uses MinIO play server at --- https://play.min.io. The endpoint and associated --- credentials are provided via the libary constant, --- --- > minioPlayCI :: ConnectInfo --- - -main :: IO () -main = do - let - bucket = "my-bucket" - object = "my-object" - res <- runMinio minioPlayCI $ do - src <- getObject bucket object def - C.connect src $ CB.sinkFileCautious "/tmp/my-object" - - case res of - Left e -> putStrLn $ "getObject failed." ++ (show e) - Right _ -> putStrLn "getObject succeeded." -``` - - -### putObject :: Bucket -> Object -> C.ConduitM () ByteString Minio () -> Maybe Int64 -> PutObjectOptions -> Minio () -Uploads an object to a bucket in the service, from the given input -byte stream of optionally supplied length. Optionally you can also specify -additional metadata for the object. - -__Parameters__ - -In the expression `putObject bucketName objectName inputSrc` the parameters -are: - -| Param | Type | Description | -|:-------------|:------------------------------------|:------------------------------------------------------------------| -| `bucketName` | _Bucket_ (alias for `Text`) | Name of the bucket | -| `objectName` | _Object_ (alias for `Text`) | Name of the object | -| `inputSrc` | _C.ConduitM () ByteString Minio ()_ | A Conduit producer of `ByteString` values | -| `size` | _Int64_ | Provide stream size (optional) | -| `opts` | _PutObjectOptions_ | Optional parameters to provide additional metadata for the object | - -__Example__ - -```haskell -{-# LANGUAGE OverloadedStrings #-} -import Network.Minio - -import qualified Data.Conduit.Combinators as CC - -import Prelude - --- | The following example uses MinIO play server at --- https://play.min.io. The endpoint and associated --- credentials are provided via the libary constant, --- --- > minioPlayCI :: ConnectInfo --- - -main :: IO () -main = do - let - bucket = "test" - object = "obj" - localFile = "/etc/lsb-release" - kb15 = 15 * 1024 - - -- Eg 1. Upload a stream of repeating "a" using putObject with default options. - res <- runMinio minioPlayCI $ - putObject bucket object (CC.repeat "a") (Just kb15) def - case res of - Left e -> putStrLn $ "putObject failed." ++ show e - Right () -> putStrLn "putObject succeeded." - -``` - - -### fGetObject :: Bucket -> Object -> FilePath -> GetObjectOptions -> Minio () -Downloads an object from a bucket in the service, to the given file - -__Parameters__ - -In the expression `fGetObject bucketName objectName inputFile` the parameters -are: - -| Param | Type | Description | -|:-------------|:----------------------------|:----------------------------------------------------------------------------| -| `bucketName` | _Bucket_ (alias for `Text`) | Name of the bucket | -| `objectName` | _Object_ (alias for `Text`) | Name of the object | -| `inputFile` | _FilePath_ | Path to the file to be uploaded | -| `opts` | _GetObjectOptions_ | Options for GET requests specifying additional options like If-Match, Range | - - -__GetObjectOptions record type__ - -| Field | Type | Description | -|:-----------------------|:--------------------------------|:------------------------------------------------------------------------------------------------------| -| `gooRange` | `Maybe ByteRanges` | Represents the byte range of object. E.g ByteRangeFromTo 0 9 represents first ten bytes of the object | -| `gooIfMatch` | `Maybe ETag` (alias for `Text`) | (Optional) ETag of object should match | -| `gooIfNoneMatch` | `Maybe ETag` (alias for `Text`) | (Optional) ETag of object shouldn't match | -| `gooIfUnmodifiedSince` | `Maybe UTCTime` | (Optional) Time since object wasn't modified | -| `gooIfModifiedSince` | `Maybe UTCTime` | (Optional) Time since object was modified | - -``` haskell - -{-# Language OverloadedStrings #-} -import Network.Minio - -import Data.Conduit (($$+-)) -import Data.Conduit.Binary (sinkLbs) -import Prelude - --- | The following example uses MinIO play server at --- https://play.min.io. The endpoint and associated --- credentials are provided via the libary constant, --- --- > minioPlayCI :: ConnectInfo --- - -main :: IO () -main = do - let - bucket = "my-bucket" - object = "my-object" - localFile = "/etc/lsb-release" - - res <- runMinio minioPlayCI $ do - src <- fGetObject bucket object localFile def - (src $$+- sinkLbs) - - case res of - Left e -> putStrLn $ "fGetObject failed." ++ (show e) - Right _ -> putStrLn "fGetObject succeeded." -``` - - -### fPutObject :: Bucket -> Object -> FilePath -> Minio () -Uploads an object to a bucket in the service, from the given file - -__Parameters__ - -In the expression `fPutObject bucketName objectName inputFile` the parameters -are: - -| Param | Type | Description | -|:-------------|:----------------------------|:--------------------------------| -| `bucketName` | _Bucket_ (alias for `Text`) | Name of the bucket | -| `objectName` | _Object_ (alias for `Text`) | Name of the object | -| `inputFile` | _FilePath_ | Path to the file to be uploaded | - -__Example__ - -```haskell -{-# Language OverloadedStrings #-} -import Network.Minio -import qualified Data.Conduit.Combinators as CC - -main :: IO () -main = do - let - bucket = "mybucket" - object = "myobject" - localFile = "/etc/lsb-release" - - res <- runMinio minioPlayCI $ do - fPutObject bucket object localFile - - case res of - Left e -> putStrLn $ "Failed to fPutObject " ++ show bucket ++ "/" ++ show object - Right _ -> putStrLn "fPutObject was successful" -``` - - -### copyObject :: DestinationInfo -> SourceInfo -> Minio () -Copies content of an object from the service to another - -__Parameters__ - -In the expression `copyObject dstInfo srcInfo` the parameters -are: - -| Param | Type | Description | -|:----------|:------------------|:----------------------------------------------------------| -| `dstInfo` | _DestinationInfo_ | A value representing properties of the destination object | -| `srcInfo` | _SourceInfo_ | A value representing properties of the source object | - - -__SourceInfo record type__ - -| Field | Type | Description | -|:-----------------------|:-----------------------|:----------------------------------------------------------------------------------------------------------| -| `srcBucket` | `Bucket` | Name of source bucket | -| `srcObject` | `Object` | Name of source object | -| `srcRange` | `Maybe (Int64, Int64)` | (Optional) Represents the byte range of source object. (0, 9) represents first ten bytes of source object | -| `srcIfMatch` | `Maybe Text` | (Optional) ETag source object should match | -| `srcIfNoneMatch` | `Maybe Text` | (Optional) ETag source object shouldn't match | -| `srcIfUnmodifiedSince` | `Maybe UTCTime` | (Optional) Time since source object wasn't modified | -| `srcIfModifiedSince` | `Maybe UTCTime` | (Optional) Time since source object was modified | - -__Destination record type__ - -| Field | Type | Description | -|:------------|:---------|:-----------------------------------------------------| -| `dstBucket` | `Bucket` | Name of destination bucket in server-side copyObject | -| `dstObject` | `Object` | Name of destination object in server-side copyObject | - -__Example__ - -```haskell -{-# Language OverloadedStrings #-} -import Network.Minio - -main :: IO () -main = do - let - bucket = "mybucket" - object = "myobject" - objectCopy = "obj-copy" - - res <- runMinio minioPlayCI $ do - copyObject def { dstBucket = bucket, dstObject = objectCopy } def { srcBucket = bucket, srcObject = object } - - case res of - Left e -> putStrLn $ "Failed to copyObject " ++ show bucket ++ show "/" ++ show object - Right _ -> putStrLn "copyObject was successful" -``` - - -### removeObject :: Bucket -> Object -> Minio () -Removes an object from the service - -__Parameters__ - -In the expression `removeObject bucketName objectName` the parameters -are: - -| Param | Type | Description | -|:-------------|:----------------------------|:-------------------| -| `bucketName` | _Bucket_ (alias for `Text`) | Name of the bucket | -| `objectName` | _Object_ (alias for `Text`) | Name of the object | - -__Example__ - -```haskell -{-# Language OverloadedStrings #-} -import Network.Minio - -main :: IO () -main = do - let - bucket = "mybucket" - object = "myobject" - - res <- runMinio minioPlayCI $ do - removeObject bucket object - - case res of - Left e -> putStrLn $ "Failed to remove " ++ show bucket ++ "/" ++ show object - Right _ -> putStrLn "Removed object successfully" -``` - - -### removeIncompleteUpload :: Bucket -> Object -> Minio () -Removes an ongoing multipart upload of an object from the service - -__Parameters__ - -In the expression `removeIncompleteUpload bucketName objectName` the parameters -are: - -| Param | Type | Description | -|:-------------|:----------------------------|:-------------------| -| `bucketName` | _Bucket_ (alias for `Text`) | Name of the bucket | -| `objectName` | _Object_ (alias for `Text`) | Name of the object | - -__Example__ - -```haskell -{-# Language OverloadedStrings #-} -import Network.Minio - -main :: IO () -main = do - let - bucket = "mybucket" - object = "myobject" - - res <- runMinio minioPlayCI $ - removeIncompleteUpload bucket object - - case res of - Left _ -> putStrLn $ "Failed to remove " ++ show bucket ++ "/" ++ show object - Right _ -> putStrLn "Removed incomplete upload successfully" -``` - - -### selectObjectContent :: Bucket -> Object -> SelectRequest -> Minio (ConduitT () EventMessage Minio ()) -Removes an ongoing multipart upload of an object from the service - -__Parameters__ - -In the expression `selectObjectContent bucketName objectName selReq` -the parameters are: - -| Param | Type | Description | -|:-------------|:----------------------------|:--------------------------| -| `bucketName` | _Bucket_ (alias for `Text`) | Name of the bucket | -| `objectName` | _Object_ (alias for `Text`) | Name of the object | -| `selReq` | _SelectRequest_ | Select request parameters | - -__SelectRequest record__ - -This record is created using `selectRequest`. Please refer to the Haddocks for further information. - -__Return Value__ - -The return value can be used to read individual `EventMessage`s in the response. Please refer to the Haddocks for further information. - -|Return type | Description | -|:---|:---| -| _Minio (C.conduitT () EventMessage Minio ())_ | A Conduit source of `EventMessage` values. | - -__Example__ - -```haskell -{-# Language OverloadedStrings #-} -import Network.Minio - -import qualified Conduit as C - -main :: IO () -main = do - let - bucket = "mybucket" - object = "myobject" - - res <- runMinio minioPlayCI $ do - let sr = selectRequest "Select * from s3object" - defaultCsvInput defaultCsvOutput - res <- selectObjectContent bucket object sr - C.runConduit $ res C..| getPayloadBytes C..| C.stdoutC - - case res of - Left _ -> putStrLn "Failed!" - Right _ -> putStrLn "Success!" -``` - - - -### bucketExists :: Bucket -> Minio Bool Checks if a bucket exists. __Parameters__ -In the expression `bucketExists bucketName` the parameters are: -| Param | Type | Description | -|:-------------|:----------------------------|:-------------------| -| `bucketName` | _Bucket_ (alias for `Text`) | Name of the bucket | +| Param | Type | Description | +|-------------------------|------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `bucketName` | _string_ | Name of the bucket. | +| `callback(err, exists)` | _function_ | `exists` is a boolean which indicates whether `bucketName` exists or not. `err` is set when an error occurs during the operation. If no callback is passed, a `Promise` is returned. | + +__Example__ + + +```js +minioClient.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__ + + +| Param | Type | Description | +|-----------------|------------|-----------------------------------------------------------------------------------------------------------| +| `bucketName` | _string_ | Name of the bucket. | +| `callback(err)` | _function_ | `err` is `null` if the bucket is removed successfully. If no callback is passed, a `Promise` is returned. | + +__Example__ + + +```js +minioClient.removeBucket('mybucket', function(err) { + if (err) return console.log('unable to remove bucket.') + console.log('Bucket removed successfully.') +}) +``` + + +### listObjects(bucketName, prefix, recursive [,listOpts]) + +Lists all objects in a bucket. + +__Parameters__ + + +| Param | Type | Description | +|--------------|----------|---------------------------------------------------------------------------------------------------------------------------------------| +| `bucketName` | _string_ | Name of the bucket. | +| `prefix` | _string_ | The prefix of the objects that should be listed (optional, default `''`). | +| `recursive` | _bool_ | `true` indicates recursive style listing and `false` indicates directory style listing delimited by '/'. (optional, default `false`). | +| `listOpts` | _object_ | query params to list object which can have `{IncludeVersion: _bool_ }` (optional) | + +__Return Value__ + + +| Param | Type | Description | +| ---- | ---- | ---- | +| `stream` | _Stream_ | Stream emitting the objects in the bucket. | + +The object is of the format: + +| Param | Type | Description | +|----------------------|-----------|--------------------------------| +| `obj.name` | _string_ | name of the object. | +| `obj.prefix` | _string_ | name of the object prefix. | +| `obj.size` | _number_ | size of the object. | +| `obj.etag` | _string_ | etag of the object. | +| `obj.versionId` | _string_ | versionId of the object. | +| `obj.isDeleteMarker` | _boolean_ | true if it is a delete marker. | +| `obj.lastModified` | _Date_ | modified time stamp. | + +__Example__ + + +```js +var data = [] +var stream = minioClient.listObjects('mybucket','', true) +stream.on('data', function(obj) { data.push(obj) } ) +stream.on("end", function (obj) { console.log(data) }) +stream.on('error', function(err) { console.log(err) } ) +``` + +__Example1__ +To get Object versions + +```js +var data = [] +var stream = minioClient.listObjects('mybucket','', true, {IncludeVersion:true}) +stream.on('data', function(obj) { data.push(obj) } ) +stream.on("end", function (obj) { console.log(data) }) +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__ + + +| Param | Type | Description | +|--------------|----------|---------------------------------------------------------------------------------------------------------------------------------------| +| `bucketName` | _string_ | Name of the bucket. | +| `prefix` | _string_ | The prefix of the objects that should be listed (optional, default `''`). | +| `recursive` | _bool_ | `true` indicates recursive style listing and `false` indicates directory style listing delimited by '/'. (optional, default `false`). | +| `startAfter` | _string_ | Specifies the object name to start after when listing objects in a bucket. (optional, default `''`). | + + +__Return Value__ + +| Param | Type | Description | +|----------|----------|--------------------------------------------| +| `stream` | _Stream_ | Stream emitting the objects in the bucket. | + +The object is of the format: + +| Param | Type | Description | +|--------------------|----------|----------------------------| +| `obj.name` | _string_ | name of the object. | +| `obj.prefix` | _string_ | name of the object prefix. | +| `obj.size` | _number_ | size of the object. | +| `obj.etag` | _string_ | etag of the object. | +| `obj.lastModified` | _Date_ | modified time stamp. | + + +__Example__ + +```js +var stream = minioClient.listObjectsV2('mybucket','', true,'') +stream.on('data', function(obj) { console.log(obj) } ) +stream.on('error', function(err) { console.log(err) } ) +``` + + +### listObjectsV2WithMetadata(bucketName, prefix, recursive, startAfter) + +Lists all objects and their metadata in a bucket using S3 listing objects V2 API + +__Parameters__ + + +| Param | Type | Description | +|--------------|----------|---------------------------------------------------------------------------------------------------------------------------------------| +| `bucketName` | _string_ | Name of the bucket. | +| `prefix` | _string_ | The prefix of the objects that should be listed (optional, default `''`). | +| `recursive` | _bool_ | `true` indicates recursive style listing and `false` indicates directory style listing delimited by '/'. (optional, default `false`). | +| `startAfter` | _string_ | Specifies the object name to start after when listing objects in a bucket. (optional, default `''`). | + + +__Return Value__ + +| Param | Type | Description | +|----------|----------|--------------------------------------------| +| `stream` | _Stream_ | Stream emitting the objects in the bucket. | + +The object is of the format: + +| Param | Type | Description | +|--------------------|----------|----------------------------| +| `obj.name` | _string_ | name of the object. | +| `obj.prefix` | _string_ | name of the object prefix. | +| `obj.size` | _number_ | size of the object. | +| `obj.etag` | _string_ | etag of the object. | +| `obj.lastModified` | _Date_ | modified time stamp. | +| `obj.metadata` | _object_ | metadata of the object. | + +__Example__ + + +```js +var stream = minioClient.extensions.listObjectsV2WithMetadata('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__ + + +| Param | Type | Description | +|--------------|----------|---------------------------------------------------------------------------------------------------------------------------------------| +| `bucketName` | _string_ | Name of the bucket. | +| `prefix` | _string_ | Prefix of the object names that are partially uploaded. (optional, default `''`) | +| `recursive` | _bool_ | `true` indicates recursive style listing and `false` indicates directory style listing delimited by '/'. (optional, default `false`). | + +__Return Value__ + + +| Param | Type | Description | +|----------|----------|-------------------------------------------| +| `stream` | _Stream_ | Emits objects of the format listed below: | + +| Param | Type | Description | +|-----------------|-----------|----------------------------------------| +| `part.key` | _string_ | name of the object. | +| `part.uploadId` | _string_ | upload ID of the object. | +| `part.size` | _Integer_ | size of the partially uploaded object. | + +__Example__ + + +```js +var Stream = minioClient.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) +}) +``` + + +### getBucketVersioning(bucketName) + +Get Versioning state of a Bucket + +__Parameters__ + +| Param | Type | Description | +|----------------------|------------|----------------------------------------------------------------------------------------------------------------------------------| +| `bucketName` | _string_ | Name of the bucket. | +| `callback(err, res)` | _function_ | Callback is called with `err` in case of error. `res` is the response object. If no callback is passed, a `Promise` is returned. | + +__Example__ +```js +minioClient.getBucketVersioning('bucketname', function (err,res){ + if (err) { + return console.log(err) + } + console.log(res) + console.log("Success") +}) +``` + + +### setBucketVersioning(bucketName, versioningConfig, callback) + +Set Versioning state on a Bucket + +__Parameters__ + + +| Param | Type | Description | +|--------------------|------------|----------------------------------------------------| +| `bucketName` | _string_ | Name of the bucket. | +| `versioningConfig` | _object_ | Versioning Configuration e.g: `{Status:"Enabled"}` | +| `callback(err)` | _function_ | Callback is called with `err` in case of error. | + +__Example__ +```js +var versioningConfig = {Status:"Enabled"} +minioClient.setBucketVersioning('bucketname',versioningConfig, function (err){ + if (err) { + return console.log(err) + } + console.log("Success") +}) +``` + + + +### setBucketReplication(bucketName, replicationConfig, callback) + +Set replication config on a Bucket + +__Parameters__ + + +| Param | Type | Description | +|---------------------|------------|--------------------------------------------------| +| `bucketName` | _string_ | Name of the bucket. | +| `replicationConfig` | _object_ | replicationConfig Configuration as a JSON Object | +| `callback(err)` | _function_ | Callback is called with `err` in case of error. | + +__Example__ +```js +const arnFromMcCli = "arn:minio:replication::1277fcbe7df0bab76ab0c64cf7c45a0d27e01917ee5f11e913f3478417833660:destination" + +var replicationConfig = { + role:arnFromMcCli, + rules:[{ + "DeleteMarkerReplication": { + "Status": "Disabled" + }, + "DeleteReplication": { + "Status": [ + ] + }, + "Destination": { + "Bucket": "arn:aws:s3:::destination" + }, + "Priority": "1", + "Status": "Enabled" + }] +} + +minioClient.setBucketReplication('bucketname',replicationConfig, function (err){ + if (err) { + return console.log(err) + } + console.log("Success") +}) + +``` + + +### getBucketReplication(bucketName, callback) + +Get replication config of a Bucket + +__Parameters__ + + +| Param | Type | Description | +|------------------------------------|------------|----------------------------------------------------------------------------------------------------------------------------------------------------| +| `bucketName` | _string_ | Name of the bucket. | +| `callback(err, replicationConfig)` | _function_ | Callback is called with `err` in case of error. else returns the info in`replicationConfig` ,which contains`{role: __string__, rules:__Array__ }`. | + +__Example__ +```js +minioClient.getBucketReplication('bucketname', function (err,replicationConfig){ + if (err) { + return console.log(err) + } + console.log(replicationConfig) +}) + +``` + + +### removeBucketReplication(bucketName, callback) + +Remove replication config of a Bucket + +__Parameters__ + +| Param | Type | Description | +|-----------------|------------|-------------------------------------------------| +| `bucketName` | _string_ | Name of the bucket. | +| `callback(err)` | _function_ | Callback is called with `err` in case of error. | + +__Example__ +```js +minioClient.removeBucketReplication('bucketname', function (err,replicationConfig){ + if (err) { + return console.log(err) + } + console.log("Success") +}) + +``` + + +### setBucketTagging(bucketName, tags, callback) + +Set Tags on a Bucket + +__Parameters__ + +| Param | Type | Description | +|-----------------|------------|-----------------------------------------------------------| +| `bucketName` | _string_ | Name of the bucket. | +| `tags` | _object_ | Tags map Configuration e.g: `{:}` | +| `callback(err)` | _function_ | Callback is called with `err` in case of error. | + +__Example__ +```js +minioClient.setBucketTagging('bucketname',tags, function (err){ + if (err) { + return console.log(err) + } + console.log("Success") +}) +``` + + +### removeBucketTagging(bucketName, callback) + +Remove Tags on a Bucket + +__Parameters__ + +| Param | Type | Description | +|-----------------|------------|-------------------------------------------------| +| `bucketName` | _string_ | Name of the bucket. | +| `callback(err)` | _function_ | Callback is called with `err` in case of error. | + +__Example__ +```js +minioClient.removeBucketTagging('bucketname', function (err){ + if (err) { + return console.log(err) + } + console.log("Success") +}) +``` + + +### getBucketTagging(bucketName, callback) + +Remove Tags on a Bucket + +__Parameters__ + +| Param | Type | Description | +|---------------------------|------------|-------------------------------------------------| +| `bucketName` | _string_ | Name of the bucket. | +| `callback(err, tagsList)` | _function_ | Callback is called with `err` in case of error. | + +__Example__ +```js +minioClient.getBucketTagging('bucketname', function (err, tagsList){ + if (err) { + return console.log(err) + } + console.log("Success",tagsList) +}) +``` + + + +### setBucketLifecycle(bucketName, lifecycleConfig, callback) + +Set Lifecycle Configuration on a Bucket + +__Parameters__ + +| Param | Type | Description | +|-------------------|------------|------------------------------------------------------------------------------------| +| `bucketName` | _string_ | Name of the bucket. | +| `lifecycleConfig` | _object_ | Valid Lifecycle Configuration or ( `null` or `''` ) to remove policy configuration | +| `callback(err)` | _function_ | Callback is called with `err` in case of error. | + +__Example__ +```js +const lifecycleConfig= { + Rule: [{ + "ID": "Transition and Expiration Rule", + "Status": "Enabled", + "Filter": { + "Prefix":"", + }, + "Expiration": { + "Days": "3650" + } + } + ] +} + +minioClient.setBucketLifecycle('bucketname',lifecycleConfig, function (err) { + if (err) { + return console.log(err) + } + console.log("Success") +}) +``` + + + + +### getBucketLifecycle(bucketName, callback) + +Get Lifecycle Configuration of a Bucket + +__Parameters__ + +| Param | Type | Description | +|------------------------------------|------------|---------------------------------------------------------------------------------------------------| +| `bucketName` | _string_ | Name of the bucket. | +| `callback(error, lifecycleConfig)` | _function_ | Callback is called with `lifecycleConfig` in case of success. Otherwise it is called with `error` | + +__Example__ +```js +minioClient.getBucketLifecycle('bucketname', function (err, lifecycleConfig) { + if (err) { + return console.log(err) + } + console.log("Success", lifecycleConfig) +}) +``` + + +### removeBucketLifecycle(bucketName, callback) + +Remove Lifecycle Configuration of a Bucket + +__Parameters__ + +| Param | Type | Description | +|-----------------|------------|-------------------------------------------------| +| `bucketName` | _string_ | Name of the bucket. | +| `callback(err)` | _function_ | Callback is called with `err` in case of error. | + +__Example__ +```js + +minioClient.removeBucketLifecycle('bucketname', function (err) { + if (err) { + return console.log(err) + } + console.log("Success") +}) +``` + + + +### setObjectLockConfig(bucketName, lockConfig [, callback]) + +Set Object lock config on a Bucket + +__Parameters__ + + +| Param | Type | Description | +|-----------------|------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `bucketName` | _string_ | Name of the bucket. | +| `lockConfig` | _object_ | Lock Configuration can be either `{}` to reset or object with all of the following key/value pairs: `{mode: ["COMPLIANCE"/'GOVERNANCE'], unit: ["Days"/"Years"], validity: }` | +| `callback(err)` | _function_ | Callback is called with `err` in case of error. | + +__Example 1__ + +```js +s3Client.setObjectLockConfig('my-bucketname', {mode:"COMPLIANCE", unit:'Days', validity:10 }, function (err){ + if (err) { + return console.log(err) + } + console.log("Success") +}) +``` + +__Example 2__ +To reset/remove object lock config on a bucket. + +```js +s3Client.setObjectLockConfig('my-bucketname', {}, function (err){ +if (err) { +return console.log(err) +} +console.log("Success") +}) +``` + + + +### getObjectLockConfig(bucketName [, callback]) + +Get Lock config on a Bucket + +__Parameters__ + + +| Param | Type | Description | +|-----------------------------|------------|-------------------------------------------------------------------------------------------| +| `bucketName` | _string_ | Name of the bucket. | +| `callback(err, lockConfig)` | _function_ | Callback is called with `err` in case of error. else it is called with lock configuration | + +__Example __ +Get object lock configuration on a Bucket + +```js +s3Client.getObjectLockConfig('my-bucketname', function (err, lockConfig){ + if (err) { + return console.log(err) + } + console.log(lockConfig) +}) +``` + + +### setBucketEncryption(bucketName [,encryptionConfig, callback]) + +Set encryption configuration on a Bucket + +__Parameters__ + + +| Param | Type | Description | +|--------------------|------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `bucketName` | _string_ | Name of the bucket. | +| `encryptionConfig` | _object_ | Encryption Configuration can be either omitted or `{}` or a valid and supported encryption config. by default: `{Rule:[{ApplyServerSideEncryptionByDefault:{SSEAlgorithm:"AES256"}}]}` is applied. | +| `callback(err)` | _function_ | Callback is called with `err` in case of error. | + +__Example __ +Set Encryption configuration on a Bucket + +```js +s3Client.setBucketEncryption('my-bucketname', function (err, lockConfig){ + if (err) { + return console.log(err) + } + console.log(lockConfig) +}) +``` + +__Example 1__ +Set Encryption configuration on a Bucket with an Algorithm + +```js +s3Client.setBucketEncryption('my-bucketname',{Rule:[{ApplyServerSideEncryptionByDefault:{SSEAlgorithm:"AES256"}}]}, function (err, lockConfig){ + if (err) { + return console.log(err) + } + console.log("Success") +}) +``` + + +### getBucketEncryption(bucketName [, callback]) + +Get encryption configuration of a Bucket + +__Parameters__ + + +| Param | Type | Description | +|----------------------------|------------|-------------------------------------------------------------------------------------------| +| `bucketName` | _string_ | Name of the bucket. | +| `callback(err, encConfig)` | _function_ | Callback is called with `err` in case of error. else it is called with lock configuration | + +__Example __ +Get Encryption configuration of a Bucket + +```js +s3Client.getBucketEncryption('my-bucketname', function (err, encConfig){ + if (err) { + return console.log(err) + } + console.log(encConfig) +}) +``` + + +### removeBucketEncryption(bucketName [, callback]) + +Remove encryption configuration of a Bucket + +__Parameters__ + + +| Param | Type | Description | +|-----------------|------------|-------------------------------------------------| +| `bucketName` | _string_ | Name of the bucket. | +| `callback(err)` | _function_ | Callback is called with `err` in case of error. | + +__Example __ +Remove Encryption configuration of a Bucket + +```js +s3Client.removeBucketEncryption('my-bucketname', function (err){ + if (err) { + return console.log(err) + } + console.log("Success") +}) +``` + +## 3. Object operations + + +### getObject(bucketName, objectName, getOpts[, callback]) + +Downloads an object as a stream. + +__Parameters__ + + +| Param | Type | Description | +|-------------------------|------------|-------------------------------------------------------------------------------------------------------------------------------------------| +| `bucketName` | _string_ | Name of the bucket. | +| `objectName` | _string_ | Name of the object. | +| `getOpts` | _object_ | Version of the object in the form `{versionId:"my-versionId"}`. Default is `{}`. (optional) | +| `callback(err, stream)` | _function_ | Callback is called with `err` in case of error. `stream` is the object content stream. If no callback is passed, a `Promise` is returned. | + +__Return Value__ + +| Param | Type | Description | +|----------|----------|-------------------------------------| +| `stream` | _Stream_ | Stream emitting the object content. | + +__Example__ + + +```js +var size = 0 +minioClient.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) + }) +}) +``` + +__Example__ + +Get a specific object version. +```js +var size = 0 +minioClient.getObject('mybucket', 'photo.jpg', {versionId:"my-versionId"}, 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, getOpts[, callback]) + +Downloads the specified range bytes of an object as a stream. + +__Parameters__ + + +| Param | Type | Description | +|-------------------------|------------|-------------------------------------------------------------------------------------------------------------------------------------------| +| `bucketName` | _string_ | Name of the bucket. | +| `objectName` | _string_ | Name of the object. | +| `offset` | _number_ | `offset` of the object from where the stream will start. | +| `length` | _number_ | `length` of the object that will be read in the stream (optional, if not specified we read the rest of the file from the offset). | +| `getOpts` | _object_ | Version of the object in the form `{versionId:'my-versionId'}`. Default is `{}`. (optional) | +| `callback(err, stream)` | _function_ | Callback is called with `err` in case of error. `stream` is the object content stream. If no callback is passed, a `Promise` is returned. | + + +__Return Value__ + +| Param | Type | Description | +| ---- | ---- | ---- | +| `stream` | _Stream_ | Stream emitting the object content. | + +__Example__ + + +```js +var size = 0 +// reads 30 bytes from the offset 10. +minioClient.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) + }) +}) +``` +__Example__ +To get a specific version of an object + +```js +var versionedObjSize = 0 +// reads 30 bytes from the offset 10. +minioClient.getPartialObject('mybucket', 'photo.jpg', 10, 30, {versionId:"my-versionId"}, function(err, dataStream) { + if (err) { + return console.log(err) + } + dataStream.on('data', function(chunk) { + versionedObjSize += chunk.length + }) + dataStream.on('end', function() { + console.log('End. Total size = ' + versionedObjSize) + }) + dataStream.on('error', function(err) { + console.log(err) + }) +}) +``` + + + +### fGetObject(bucketName, objectName, filePath, getOpts[, callback]) + +Downloads and saves the object as a file in the local filesystem. + +__Parameters__ + +| Param | Type | Description | +|-----------------|------------|----------------------------------------------------------------------------------------------------| +| `bucketName` | _string_ | Name of the bucket. | +| `objectName` | _string_ | Name of the object. | +| `filePath` | _string_ | Path on the local filesystem to which the object data will be written. | +| `getOpts` | _object_ | Version of the object in the form `{versionId:'my-versionId'}`. Default is `{}`. (optional) | +| `callback(err)` | _function_ | Callback is called with `err` in case of error. If no callback is passed, a `Promise` is returned. | + +__Return Value__ + +| Value | Type | Description | +|--------|----------|--------------------------------------------------| +| `err` | _object_ | Error in case of any failures | +| `file` | _file_ | Streamed Output file at the specified `filePath` | + +__Example__ + + +```js +var size = 0 +minioClient.fGetObject('mybucket', 'photo.jpg', '/tmp/photo.jpg', function(err) { + if (err) { + return console.log(err) + } + console.log('success') +}) +``` + +__Example__ +To Stream a specific object version into a file. + +```js +minioClient.fGetObject(bucketName, objNameValue, './download/MyImage.jpg', {versionId:"my-versionId"}, function(e) { + if (e) { + return console.log(e) + } + console.log('success') +}) + +``` + + +### putObject(bucketName, objectName, stream, size, metaData[, callback]) + +Uploads an object from a stream/Buffer. + + +##### From a stream + +__Parameters__ + + +| Param | Type | Description | +|--------------------------|---------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `bucketName` | _string_ | Name of the bucket. | +| `objectName` | _string_ | Name of the object. | +| `stream` | _Stream_ | Readable stream. | +| `size` | _number_ | Size of the object (optional). | +| `metaData` | _Javascript Object_ | metaData of the object (optional). | +| `callback(err, objInfo)` | _function_ | Non-null `err` indicates error, in case of Success,`objInfo` contains `etag` _string_ and `versionId` _string_ of the object. If no callback is passed, a `Promise` is returned. | + + +__Return Value__ + +| Value | Type | Description | +|---------------------|----------|-------------------------------------| +| `err` | _object_ | Error in case of any failures | +| `objInfo.etag` | _string_ | `etag` of an object | +| `objInfo.versionId` | _string_ | `versionId` of an object (optional) | + + +__Example__ + +The maximum size of a single object is limited to 5TB. putObject transparently uploads objects larger than 64MiB in multiple parts. Uploaded data is carefully verified using MD5SUM signatures. + +```js +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) + } + minioClient.putObject('mybucket', '40mbfile', fileStream, stats.size, function(err, objInfo) { + if(err) { + return console.log(err) // err should be null + } + console.log("Success", objInfo) + }) +}) +``` + +##### From a "Buffer" or a "string" + +__Parameters__ + + +| Param | Type | Description | +|-----------------------|----------------------|-------------------------------------------------------------------------------------| +| `bucketName` | _string_ | Name of the bucket. | +| `objectName` | _string_ | Name of the object. | +| `string or Buffer` | _Stream_ or _Buffer_ | Readable stream. | +| `metaData` | _Javascript Object_ | metaData of the object (optional). | +| `callback(err, etag)` | _function_ | Non-null `err` indicates error, `etag` _string_ is the etag of the object uploaded. | + + +__Example__ + + +```js +var buffer = 'Hello World' +minioClient.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__ + + +| Param | Type | Description | +|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------|----------------------------------| +| `bucketName` | _string_ | Name of the bucket. | +| `objectName` | _string_ | Name of the object. | +| `filePath` | _string_ | Path of the file to be uploaded. | +| `metaData` | _Javascript Object_ | Metadata of the object. | +| `callback(err, objInfo)` _function_: non null `err` indicates error, `objInfo` _object_ is the information about the object uploaded which contains `versionId` string and `etag` string. | | | + +__Return Value__ + +| Value | Type | Description | +|---------------------|----------|-------------------------------------| +| `err` | _object_ | Error in case of any failures | +| `objInfo.etag` | _string_ | `etag` of an object | +| `objInfo.versionId` | _string_ | `versionId` of an object (optional) | + +__Example__ + +The maximum size of a single object is limited to 5TB. fPutObject transparently uploads objects larger than 64MiB in multiple parts. Uploaded data is carefully verified using MD5SUM signatures. + +```js +var file = '/tmp/40mbfile' +var metaData = { + 'Content-Type': 'text/html', + 'Content-Language': 123, + 'X-Amz-Meta-Testing': 1234, + 'example': 5678 +} +minioClient.fPutObject('mybucket', '40mbfile', file, metaData, function(err, objInfo) { + if(err) { + return console.log(err) + } + console.log("Success", objInfo.etag, objInfo.versionId) +}) +``` + + +### copyObject(bucketName, objectName, sourceObject, conditions[, callback]) + +Copy a source object into a new object in the specified bucket. + +__Parameters__ + + +| Param | Type | Description | +|---------------------------------------|------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `bucketName` | _string_ | Name of the bucket. | +| `objectName` | _string_ | Name of the object. | +| `sourceObject` | _string_ | Path of the file to be copied. | +| `conditions` | _CopyConditions_ | Conditions to be satisfied before allowing object copy. | +| `callback(err, {etag, lastModified})` | _function_ | Non-null `err` indicates error, `etag` _string_ and lastModified _Date_ are the etag and the last modified date of the object newly copied. If no callback is passed, a `Promise` is returned. | + +__Example__ + +```js +var conds = new Minio.CopyConditions() +conds.setMatchETag('bd891862ea3e22c93ed53a098218791d') +minioClient.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, statOpts[, callback]) + +Gets metadata of an object. + +__Parameters__ + + +| Param | Type | Description | +|-----------------------|------------|-----------------------------------------------------------------------------------------------------------------------------------------------| +| `bucketName` | _string_ | Name of the bucket. | +| `objectName` | _string_ | Name of the object. | +| `statOpts` | _object_ | Version of the object in the form `{versionId:"my-versionId"}`. Default is `{}`. (optional) | +| `callback(err, stat)` | _function_ | `err` is not `null` in case of error, `stat` contains the object information listed below. If no callback is passed, a `Promise` is returned. | + +__Return Value__ + +| Param | Type | Description | +|---------------------|---------------------|---------------------------| +| `stat.size` | _number_ | size of the object. | +| `stat.etag` | _string_ | etag of the object. | +| `stat.versionId` | _string_ | version of the object. | +| `stat.metaData` | _Javascript Object_ | metadata of the object. | +| `stat.lastModified` | _Date_ | Last Modified time stamp. | + + +__Example__ + + +```js +minioClient.statObject('mybucket', 'photo.jpg', function(err, stat) { + if (err) { + return console.log(err) + } + console.log(stat) +}) +``` + +__Example stat on a version of an object__ + + +```js +minioClient.statObject('mybucket', 'photo.jpg', { versionId : "my-versionId" }, function(err, stat) { + if (err) { + return console.log(err) + } + console.log(stat) +}) +``` + + +### removeObject(bucketName, objectName [, removeOpts] [, callback]) + +Removes an object. + +__Parameters__ + + +| Param | Type | Description | +|-----------------|------------|-------------------------------------------------------------------------------------------------------------------------------| +| `bucketName` | _string_ | Name of the bucket. | +| `objectName` | _string_ | Name of the object. | +| `removeOpts` | _object_ | Version of the object in the form `{versionId:"my-versionId", governanceBypass: true or false }`. Default is `{}`. (Optional) | +| `callback(err)` | _function_ | Callback function is called with non `null` value in case of error. If no callback is passed, a `Promise` is returned. | + +__Example 1__ + +```js +minioClient.removeObject('mybucket', 'photo.jpg', function(err) { + if (err) { + return console.log('Unable to remove object', err) + } + console.log('Removed the object') +}) +``` + +__Example 2__ +Delete a specific version of an object + +```js +minioClient.removeObject('mybucket', 'photo.jpg', { versionId : "my-versionId" }, function(err) { + if (err) { + return console.log('Unable to remove object', err) + } + console.log('Removed the object') +}) +``` + +__Example 3__ +Remove an object version locked with retention mode `GOVERNANCE` using the `governanceBypass` remove option + +```js +s3Client.removeObject('my-bucketname', 'my-objectname', {versionId:"my-versionId", governanceBypass:true}, function(e) { + if (e) { + return console.log(e) + } + console.log("Success") +}) + +``` + + +### removeObjects(bucketName, objectsList[, callback]) + +Remove all objects in the objectsList. + +__Parameters__ + + +| Param | Type | Description | +|-----------------|------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `bucketName` | _string_ | Name of the bucket. | +| `objectsList` | _object_ | list of objects in the bucket to be removed. any one of the formats: 1. List of Object names as array of strings which are object keys: `['objectname1','objectname2']` 2. List of Object name and VersionId as an object: [{name:"my-obj-name",versionId:"my-versionId"}] | +| `callback(err)` | _function_ | Callback function is called with non `null` value in case of error. | + + +__Example__ + + +```js + +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') + }) + +}) + + +``` + +__Example1__ + +With versioning Support + +```js +var objectsList=[] +var bucket ="my-bucket" +var prefix="my-prefix" +var recursive=false + +var objectsStream = s3Client.listObjects(bucket, prefix, recursive, {IncludeVersion: true}) + objectsStream.on('data', function (obj) { + objectsList.push(obj) + }) + objectsStream.on('error', function (e) { + return console.log(e) + }) + objectsStream.on('end', function () { + s3Client.removeObjects(bucket, objectsList, function (e) { + if (e) { + return console.log(e) + } + console.log("Success") + }) + }) + +``` + + +### removeIncompleteUpload(bucketName, objectName[, callback]) + +Removes a partially uploaded object. + +__Parameters__ + + +| Param | Type | Description | +|-----------------|------------|------------------------------------------------------------------------------------------------------------------------| +| `bucketName` | _string_ | Name of the bucket. | +| `objectName` | _string_ | Name of the object. | +| `callback(err)` | _function_ | Callback function is called with non `null` value in case of error. If no callback is passed, a `Promise` is returned. | + + +__Example__ + + +```js +minioClient.removeIncompleteUpload('mybucket', 'photo.jpg', function(err) { + if (err) { + return console.log('Unable to remove incomplete object', err) + } + console.log('Incomplete object removed successfully.') +}) +``` + + + +### putObjectRetention(bucketName, objectName [, retentionOpts] [, callback]) + +Apply retention on an object. + +__Parameters__ + +| Param | Type | Description | +|-----------------|------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `bucketName` | _string_ | Name of the bucket. | +| `objectName` | _string_ | Name of the object. | +| `retentionOpts` | _object_ | Options for retention like : `{ governanceBypass:true/false ,mode:COMPLIANCE/GOVERNANCE, retainUntilDate: _date_ , versionId:"my-versionId" }` Default is `{}` (Optional) | +| `callback(err)` | _function_ | Callback function is called with non `null` value in case of error. If no callback is passed, a `Promise` is returned. | + + +__Example__ +Apply object retention on an object + +```js +const bucketName = 'my-bucket' +const objectName ="my-object" + +const expirationDate = new Date() +expirationDate.setDate(expirationDate.getDate() + 1) +expirationDate.setUTCHours(0,0,0,0)//Should be start of the day.(midnight) +const versionId ="e67b4b08-144d-4fc4-ba15-43c3f7f9ba74" + +const objRetPromise = minioClient.putObjectRetention( + bucketName, + objectName, + { Mode:"GOVERNANCE", retainUntilDate:retainUntilDate.toISOString(), versionId:versionId }, + function (err){ + if (err) { + return console.log(err) + } + console.log("Success") +}) +``` + + +### getObjectRetention(bucketName, objectName [, getOpts] [, callback]) + +Get retention config of an object + +__Parameters__ + +| Param | Type | Description | +|----------------------|------------|----------------------------------------------------------------------------------------------------------------------------------| +| `bucketName` | _string_ | Name of the bucket. | +| `objectName` | _string_ | Name of the object. | +| `getOpts` | _object_ | Options for retention like : `{ versionId:"my-versionId" }` Default is `{}` (Optional) | +| `callback(err, res)` | _function_ | Callback is called with `err` in case of error. `res` is the response object. If no callback is passed, a `Promise` is returned. | + +__Example__ + +```js +minioClient.getObjectRetention('bucketname', 'bucketname', { versionId: "my-versionId" }, function (err, res){ + if (err) { + return console.log(err) + } + console.log(res) +}) +``` + + +### putObjectTagging(bucketName, objectName, tags[, putOpts, callback]) + +### setObjectTagging(bucketName, objectName, tags[, putOpts, callback]) + +Put Tags on an Object + +__Parameters__ + +| Param | Type | Description | +|-----------------|------------|---------------------------------------------------------------| +| `bucketName` | _string_ | Name of the bucket. | +| `objectName` | _string_ | Name of the object. | +| `tags` | _object_ | Tags map Configuration e.g: `{:}` | +| `putOpts` | _object_ | Default is {}. e.g `{versionId:"my-version-id"}`. (Optional) | +| `callback(err)` | _function_ | Callback is called with `err` in case of error. | + +__Example__ +```js +minioClient.setObjectTagging('bucketname','object-name', tags, function (err){ + if (err) { + return console.log(err) + } + console.log("Success") +}) +``` + +__Example 1__ +Put tags on a version of an object. + +```js +minioClient.setObjectTagging('bucketname','object-name', tags, { versionId: "my-version-id" }, function (err){ + if (err) { + return console.log(err) + } + console.log("Success") +}) +``` + + +### removeObjectTagging(bucketName, objectName[, removeOpts, callback]) + +Remove Tags on an Object + +__Parameters__ + +| Param | Type | Description | +|-----------------|------------|---------------------------------------------------------------| +| `bucketName` | _string_ | Name of the bucket. | +| `objectName` | _string_ | Name of the object. | +| `removeOpts` | _object_ | Defaults to {}. e.g `{versionId:"my-version-id"}`. (Optional) | +| `callback(err)` | _function_ | Callback is called with `err` in case of error. | + +__Example__ +```js +minioClient.removeObjectTagging('bucketname','object-name', function (err){ + if (err) { + return console.log(err) + } + console.log("Success") +}) +``` + + +__Example1__ +Remove tags on a version of an object. + +```js +minioClient.removeObjectTagging('bucketname', 'object-name', {versionId:"my-object-version-id"}, function (err){ + if (err) { + return console.log(err) + } + console.log("Success") +}) +``` + + +### getObjectTagging(bucketName, objectName[, getOpts, callback]) + +Get Tags of an Object + +__Parameters__ + +| Param | Type | Description | +|-----------------|------------|---------------------------------------------------------------| +| `bucketName` | _string_ | Name of the bucket. | +| `objectName` | _string_ | Name of the object. | +| `getOpts` | _object_ | Defaults to {}. e.g `{versionId:"my-version-id"}`. (Optional) | +| `callback(err)` | _function_ | Callback is called with `err` in case of error. | + +__Example__ +```js +minioClient.getObjectTagging('bucketname', 'object-name', function (err, tagsList){ + if (err) { + return console.log(err) + } + console.log("Success", tagsList) +}) +``` + + +__Example1__ +Get tags on a version of an object. + +```js +minioClient.getObjectTagging('bucketname', 'object-name', {versionId:"my-object-version-id"}, function (err, tagsList){ + if (err) { + return console.log(err) + } + console.log("Success", tagsList) +}) +``` + + +### getObjectLegalHold(bucketName, objectName, getOpts [, callback]) + +Get legal hold on an object. + +__Parameters__ + + +| Param | Type | Description | +|-----------------|------------|------------------------------------------------------------------------------------------------------------------------| +| `bucketName` | _string_ | Name of the bucket. | +| `objectName` | _string_ | Name of the object. | +| `getOpts` | _object_ | Legal hold configuration options. e.g `{versionId:'my-version-uuid'}` defaults to `{}` . | +| `callback(err)` | _function_ | Callback function is called with non `null` value in case of error. If no callback is passed, a `Promise` is returned. | + + +__Example 1__ + +Get Legal hold of an object. + +```js +minioClient.getObjectLegalHold('bucketName', 'objectName', {}, function(err, res) { + if (err) { + return console.log('Unable to get legal hold config for the object', err.message) + } + console.log('Success', res) +}) +``` + +__Example 2__ + +Get Legal hold of an object with versionId. + +```js +minioClient.getObjectLegalHold('bucketName', 'objectName', { versionId:'my-obj-version-uuid' }, function(err, res) { + if (err) { + return console.log('Unable to get legal hold config for the object', err.message) + } + console.log('Success', res) +}) +``` + + + +### setObjectLegalHold(bucketName, objectName, [,setOpts, callback]) + +Set legal hold on an object. + +__Parameters__ + + +| Param | Type | Description | +|-----------------|------------|---------------------------------------------------------------------------------------------------------------------------------------------| +| `bucketName` | _string_ | Name of the bucket. | +| `objectName` | _string_ | Name of the object. | +| `setOpts` | _object_ | Legal hold configuration options to set. e.g `{versionId:'my-version-uuid', status:'ON or OFF'}` defaults to `{status:'ON'}` if not passed. | +| `callback(err)` | _function_ | Callback function is called with non `null` value in case of error. If no callback is passed, a `Promise` is returned. | + +__Example 1__ + +Set Legal hold of an object. +```js +minioClient.setObjectLegalHold('bucketName', 'objectName', {Status:"ON"}, function(err, res) { + if (err) { + return console.log('Unable to set legal hold config for the object', err.message) + } + console.log('Success') +}) +``` + +__Example 2__ + +Set Legal hold of an object with versionId. +```js +minioClient.setObjectLegalHold('bucketName', 'objectName', { Status:"ON", versionId:'my-obj-version-uuid' }, function(err, res) { + if (err) { + return console.log('Unable to set legal hold config for the object version', err.message) + } + console.log('Success') +}) +``` + + + +### composeObject(destObjConfig, sourceObjectList [, callback]) + +Compose an object from parts + +__Parameters__ + + +| Param | Type | Description | +|--------------------|------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `destObjConfig` | _object_ | Destination Object configuration of the type [CopyDestinationOptions](https://github.com/minio/minio-js/blob/master/src/helpers.js) | +| `sourceObjectList` | _object[]_ | Array of object(parts) source to compose into an object. Each part configuration should be of type [CopySourceOptions](https://github.com/minio/minio-js/blob/master/src/helpers.js) | +| `callback(err)` | _function_ | Callback function is called with non `null` value in case of error. If no callback is passed, a `Promise` is returned. | + + +__Example 1__ + +Compose an Object from its parts . + +```js +const sourceList = [new Helpers.CopySourceOptions( { + Bucket: "source-bucket", + Object: "parta", +}),new Helpers.CopySourceOptions({ + Bucket: "source-bucket", + Object: "partb", +}),new Helpers.CopySourceOptions({ + Bucket: "source-bucket", + Object: "partc", + +}),new Helpers.CopySourceOptions({ + Bucket: "source-bucket", + Object: "partd", +})] + +const destOption = new Helpers.CopyDestinationOptions({ + Bucket: "dest-bucket", + Object: "100MB.zip" +}) + +//using Promise style. +const composePromise = minioClient.composeObject(destOption,sourceList) + composePromise.then((result) => { + console.log("Success...") + }) + .catch((e)=>{ + console.log("error",e) + }) + +``` + + +### selectObjectContent(bucketName, objectName, selectOpts[, callback]) + +Select contents of an object (S3 Select). + +__Parameters__ + +| Param | Type | Description | +|-----------------|------------|------------------------------------------------------------------------------------------------------------------------------------------------------| +| `bucketName` | _string_ | Name of the bucket. | +| `objectName` | _string_ | Name of the object. | +| `selectOpts` | _object_ | | +| `callback(err)` | _function_ | Callback function is called with non `null` value in case of error. If no callback is passed, a `Promise` is returned, with the `SelectResults` type | + +__Example 1__ +Select all values +```js +const selectOpts = { + expression:"SELECT * FROM s3object s where s.\"Name\" = 'Jane'", + expressionType:"SQL", + inputSerialization : {'CSV': {"FileHeaderInfo": "Use", + RecordDelimiter: "\n", + FieldDelimiter: ",", + }, + 'CompressionType': 'NONE'}, + outputSerialization : {'CSV': {RecordDelimiter: "\n", + FieldDelimiter: ",",}}, + requestProgress:{Enabled:true}, +} + +minioClient.selectObjectContent('bucketName', 'objectName', selectOpts, function(err, res) { + if (err) { + return console.log('Unable to process select object content.', err.message) + } + console.log('Success') +}) +``` ## 4. Presigned operations - -### presignedGetObjectUrl :: Bucket -> Object -> UrlExpiry -> Query -> RequestHeaders -> Minio ByteString +Presigned URLs are generated for temporary download/upload access to private objects. -Generate a URL with authentication signature to GET (download) an -object. All extra query parameters and headers passed here will be -signed and are required when the generated URL is used. Query -parameters could be used to change the response headers sent by the -server. Headers can be used to set Etag match conditions among others. + +### 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. -For a list of possible request parameters and headers, please refer -to the GET object REST API AWS S3 documentation. __Parameters__ -In the expression `presignedGetObjectUrl bucketName objectName expiry queryParams headers` -the parameters are: -| Param | Type | Description | -|:--------------|:---------------------------------------------------------------|:------------------------------------------------| -| `bucketName` | _Bucket_ (alias for `Text`) | Name of the bucket | -| `objectName` | _Object_ (alias for `Text`) | Name of the object | -| `expiry` | _UrlExpiry_ (alias for `Int`) | Url expiry time in seconds | -| `queryParams` | _Query_ (from package `http-types:Network.HTTP.Types`) | Query parameters to add to the URL | -| `headers` | _RequestHeaders_ (from package `http-types:Network.HTTP.Types` | Request headers that would be used with the URL | -__Return Value__ +| Param | Type | Description | +|-------------------------------|------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `bucketName` | _string_ | Name of the bucket. | +| `objectName` | _string_ | Name of the object. | +| `expiry` | _number_ | Expiry time in seconds. Default value is 7 days. (optional) | +| `reqParams` | _object_ | request parameters. (optional) e.g {versionId:"10fa9946-3f64-4137-a58f-888065c0732e"} | +| `requestDate` | _Date_ | A date object, the url will be issued at. Default value is now. (optional) | +| `callback(err, presignedUrl)` | _function_ | Callback function is called with non `null` err value in case of error. `presignedUrl` will be the URL using which the object can be downloaded using GET request. If no callback is passed, a `Promise` is returned. | -Returns the generated URL - it will include authentication -information. -| Return type | Description | -|:-------------|:------------------------| -| _ByteString_ | Generated presigned URL | +__Example1__ -__Example__ -```haskell -{-# Language OverloadedStrings #-} - -import Network.Minio -import qualified Data.ByteString.Char8 as B - -main :: IO () -main = do - let - bucket = "mybucket" - object = "myobject" - - res <- runMinio minioPlayCI $ do - -- Set a 7 day expiry for the URL - presignedGetObjectUrl bucket object (7*24*3600) [] [] - - -- Print the URL on success. - putStrLn $ either - (("Failed to generate URL: " ++) . show) - B.unpack - res +```js +// presigned url for 'getObject' method. +// expires in a day. +minioClient.presignedUrl('GET', 'mybucket', 'hello.txt', 24*60*60, function(err, presignedUrl) { + if (err) return console.log(err) + console.log(presignedUrl) +}) ``` - -### presignedPutObjectUrl :: Bucket -> Object -> UrlExpiry -> RequestHeaders -> Minio ByteString -Generate a URL with authentication signature to PUT (upload) an -object. Any extra headers if passed, are signed, and so they are -required when the URL is used to upload data. This could be used, for -example, to set user-metadata on the object. +__Example2__ + + +```js +// presigned url for 'listObject' method. +// Lists objects in 'myBucket' with prefix 'data'. +// Lists max 1000 of them. +minioClient.presignedUrl('GET', 'mybucket', '', 1000, {'prefix': 'data', 'max-keys': 1000}, function(err, presignedUrl) { + if (err) return console.log(err) + console.log(presignedUrl) +}) +``` + +__Example 3__ + + +```js +// Get Object with versionid +minioClient.presignedUrl('GET', 'mybucket', '', 1000, {versionId: "10fa9946-3f64-4137-a58f-888065c0732e"}, 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. -For a list of possible headers to pass, please refer to the PUT object -REST API AWS S3 documentation. __Parameters__ -In the expression `presignedPutObjectUrl bucketName objectName expiry headers` -the parameters are: -| Param | Type | Description | -|:-------------|:---------------------------------------------------------------|:------------------------------------------------| -| `bucketName` | _Bucket_ (alias for `Text`) | Name of the bucket | -| `objectName` | _Object_ (alias for `Text`) | Name of the object | -| `expiry` | _UrlExpiry_ (alias for `Int`) | Url expiry time in seconds | -| `headers` | _RequestHeaders_ (from package `http-types:Network.HTTP.Types` | Request headers that would be used with the URL | -__Return Value__ +| Param | Type | Description | +|-------------------------------|------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `bucketName` | _string_ | Name of the bucket. | +| `objectName` | _string_ | Name of the object. | +| `expiry` | _number_ | Expiry time in seconds. Default value is 7 days. (optional) | +| `respHeaders` | _object_ | response headers to override (optional) | +| `requestDate` | _Date_ | A date object, the url will be issued at. Default value is now. (optional) | +| `callback(err, presignedUrl)` | _function_ | Callback function is called with non `null` err value in case of error. `presignedUrl` will be the URL using which the object can be downloaded using GET request. If no callback is passed, a `Promise` is returned. | -Returns the generated URL - it will include authentication -information. - -| Return type | Description | -|:-------------|:------------------------| -| _ByteString_ | Generated presigned URL | __Example__ -```haskell -{-# Language OverloadedStrings #-} -import Network.Minio -import qualified Data.ByteString.Char8 as B +```js +// expires in a day. +minioClient.presignedGetObject('mybucket', 'hello.txt', 24*60*60, function(err, presignedUrl) { + if (err) return console.log(err) + console.log(presignedUrl) +}) +``` -main :: IO () -main = do - let - bucket = "mybucket" - object = "myobject" + +### presignedPutObject(bucketName, objectName, expiry[, callback]) - res <- runMinio minioPlayCI $ do - -- Set a 7 day expiry for the URL - presignedPutObjectUrl bucket object (7*24*3600) [] [] +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. - -- Print the URL on success. - putStrLn $ either - (("Failed to generate URL: " ++) . show) - B.unpack - res + +__Parameters__ + + +| Param | Type | Description | +|-------------------------------|------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `bucketName` | _string_ | Name of the bucket. | +| `objectName` | _string_ | Name of the object. | +| `expiry` | _number_ | Expiry time in seconds. Default value is 7 days. | +| `callback(err, presignedUrl)` | _function_ | Callback function is called with non `null` err value in case of error. `presignedUrl` will be the URL using which the object can be uploaded using PUT request. If no callback is passed, a `Promise` is returned. | + + +__Example__ + + +```js +// expires in a day. +minioClient.presignedPutObject('mybucket', 'hello.txt', 24*60*60, function(err, presignedUrl) { + if (err) return console.log(err) + console.log(presignedUrl) +}) ``` -### presignedPostPolicy :: PostPolicy -> Minio (ByteString, HashMap Text ByteString) +### presignedPostPolicy(policy[, callback]) -Generate a presigned URL and POST policy to upload files via a POST -request. This is intended for browser uploads and generates form data -that should be submitted in the request. +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. -The `PostPolicy` argument is created using the `newPostPolicy` function: +__Parameters__ -#### newPostPolicy :: UTCTime -> [PostPolicyCondition] -> Either PostPolicyError PostPolicy -In the expression `newPostPolicy expirationTime conditions` the parameters are: +| Param | Type | Description | +|--------------------------------------|------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `policy` | _object_ | Policy object created by minioClient.newPostPolicy() | +| `callback(err, {postURL, formData})` | _function_ | Callback function is called with non `null` err value in case of error. `postURL` will be the URL using which the object can be uploaded using POST request. `formData` is the object having key/value pairs for the Form data of POST body. If no callback is passed, a `Promise` is returned. | -| Param | Type | Description | -|:-----------------|:--------------------------------------------------|:---------------------------------------------| -| `expirationTime` | _UTCTime_ (from package `time:Data.Time.UTCTime`) | The expiration time for the policy | -| `conditions` | _[PostPolicyConditions]_ | List of conditions to be added to the policy | -The policy conditions are created using various helper functions - -please refer to the Haddocks for details. +Create policy: -Since conditions are validated by `newPostPolicy` it returns an -`Either` value. -__Return Value__ +```js +var policy = minioClient.newPostPolicy() +``` + +Apply upload policy restrictions: + +```js +// Policy restricted only for bucket 'mybucket'. +policy.setBucket('mybucket') + +// Policy restricted only for hello.txt object. +policy.setKey('hello.txt') +``` +or + +```js +// 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') + +// Set content disposition response header. +policy.setContentDisposition('attachment; filename=text.txt') + +// Only allow content size in range 1KB to 1MB. +policy.setContentLengthRange(1024, 1024*1024) + +// Set key-value user defined metadata +policy.setUserMetaData({ + key: 'value' +}) +``` + +POST your content from the browser using `superagent`: + + +```js +minioClient.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__ + + + +| Param | Type | Description | +|-------------------------------------------|------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `bucketName` | _string_ | Name of the bucket. | +| `callback(err, bucketNotificationConfig)` | _function_ | Callback function is called with non `null` err value in case of error. `bucketNotificationConfig` will be the object that carries all notification configurations associated to bucketName. If no callback is passed, a `Promise` is returned. | -`presignedPostPolicy` returns a 2-tuple - the generated URL and a map -containing the form-data that should be submitted with the request. __Example__ -```haskell -{-# Language OverloadedStrings #-} -import Network.Minio - -import qualified Data.ByteString as B -import qualified Data.ByteString.Char8 as Char8 -import qualified Data.HashMap.Strict as H -import qualified Data.Text.Encoding as Enc -import qualified Data.Time as Time - -main :: IO () -main = do - now <- Time.getCurrentTime - let - bucket = "mybucket" - object = "myobject" - - -- set an expiration time of 10 days - expireTime = Time.addUTCTime (3600 * 24 * 10) now - - -- create a policy with expiration time and conditions - since the - -- conditions are validated, newPostPolicy returns an Either value - policyE = newPostPolicy expireTime - [ -- set the object name condition - ppCondKey "photos/my-object" - -- set the bucket name condition - , ppCondBucket "my-bucket" - -- set the size range of object as 1B to 10MiB - , ppCondContentLengthRange 1 (10*1024*1024) - -- set content type as jpg image - , ppCondContentType "image/jpeg" - -- on success set the server response code to 200 - , ppCondSuccessActionStatus 200 - ] - - case policyE of - Left err -> putStrLn $ show err - Right policy -> do - res <- runMinio minioPlayCI $ do - (url, formData) <- presignedPostPolicy policy - - -- a curl command is output to demonstrate using the generated - -- URL and form-data - let - formFn (k, v) = B.concat ["-F ", Enc.encodeUtf8 k, "=", - "'", v, "'"] - formOptions = B.intercalate " " $ map formFn $ H.toList formData - - - return $ B.intercalate " " $ - ["curl", formOptions, "-F file=@/tmp/photo.jpg", url] - - case res of - Left e -> putStrLn $ "post-policy error: " ++ (show e) - Right cmd -> do - putStrLn $ "Put a photo at /tmp/photo.jpg and run command:\n" - - -- print the generated curl command - Char8.putStrLn cmd +```js +minioClient.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. - - \ No newline at end of file +__Parameters__ + + +| Param | Type | Description | +|----------------------------|----------------------|----------------------------------------------------------------------------------------------------------------------------| +| `bucketName` | _string_ | Name of the bucket. | +| `bucketNotificationConfig` | _BucketNotification_ | Javascript object that carries the notification configuration. | +| `callback(err)` | _function_ | Callback function is called with non `null` err value in case of error. If no callback is passed, a `Promise` is returned. | + + +__Example__ + +```js +// Create a new notification object +var bucketNotification = new Minio.NotificationConfig(); + +// Setup a new Queue configuration +var arn = Minio.buildARN('aws', 'sqs', 'us-west-2', '1', 'webhook') +var queue = new Minio.QueueConfig(arn) +queue.addFilterSuffix('.jpg') +queue.addFilterPrefix('myphotos/') +queue.addEvent(Minio.ObjectReducedRedundancyLostObject) +queue.addEvent(Minio.ObjectCreatedAll) + +// Add the queue to the overall notification object +bucketNotification.add(queue) + +minioClient.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__ + + +| Param | Type | Description | +|-----------------|------------|----------------------------------------------------------------------------------------------------------------------------| +| `bucketName` | _string_ | Name of the bucket | +| `callback(err)` | _function_ | Callback function is called with non `null` err value in case of error. If no callback is passed, a `Promise` is returned. | + + +```js +minioClient.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 registered 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__ + +| Param | Type | Description | +|--------------|----------|-------------------------------------------------| +| `bucketName` | _string_ | Name of the bucket | +| `prefix` | _string_ | Object key prefix to filter notifications for. | +| `suffix` | _string_ | Object key suffix to filter notifications for. | +| `events` | _Array_ | Enables notifications for specific event types. | + +See [here](https://github.com/minio/minio-js/blob/master/examples/minio/listen-bucket-notification.js) for a full example. + +```js +var listener = minioClient.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__ + + +| Param | Type | Description | +|-------------------------|------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `bucketName` | _string_ | Name of the bucket | +| `callback(err, policy)` | _function_ | Callback function is called with non `null` err value in case of error. `policy` is [bucket policy](https://docs.aws.amazon.com/AmazonS3/latest/dev/example-bucket-policies.html). If no callback is passed, a `Promise` is returned. | + + +```js +// Retrieve bucket policy of 'my-bucketname' +minioClient.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](https://docs.aws.amazon.com/AmazonS3/latest/dev/example-bucket-policies.html) is detailed here. + +__Parameters__ + + +| Param | Type | Description | +|-----------------|------------|----------------------------------------------------------------------------------------------------------------------------| +| `bucketName` | _string_ | Name of the bucket. | +| `bucketPolicy` | _string_ | bucket policy. | +| `callback(err)` | _function_ | Callback function is called with non `null` err value in case of error. If no callback is passed, a `Promise` is returned. | + + +```js +// Set the bucket policy of `my-bucketname` +minioClient.setBucketPolicy('my-bucketname', JSON.stringify(policy), function(err) { + if (err) throw err + + console.log('Bucket policy set') +}) +``` +## 6. Custom Settings + + +### setS3TransferAccelerate(endpoint) +Set AWS S3 transfer acceleration endpoint for all API requests hereafter. +NOTE: This API applies only to AWS S3 and is a no operation for S3 compatible object storage services. + +__Parameters__ + +| Param | Type | Description | +|------------|----------|-----------------------------------------------| +| `endpoint` | _string_ | Set to new S3 transfer acceleration endpoint. | + + +## 7. HTTP request options +### setRequestOptions(options) + +Set the HTTP/HTTPS request options. Supported options are `agent` ([http.Agent()](https://nodejs.org/api/http.html#http_class_http_agent)), `family` ([IP address family to use while resolving `host` or `hostname`](https://nodejs.org/api/http.html#http_http_request_url_options_callback)), and tls related options ('agent', 'ca', 'cert', 'ciphers', 'clientCertEngine', 'crl', 'dhparam', 'ecdhCurve', 'honorCipherOrder', 'key', 'passphrase', 'pfx', 'rejectUnauthorized', 'secureOptions', 'secureProtocol', 'servername', 'sessionIdContext') documented [here](https://nodejs.org/api/tls.html#tls_tls_createsecurecontext_options) + +```js +// Do not reject self signed certificates. +minioClient.setRequestOptions({rejectUnauthorized: false}) +``` + + +## 7. Explore Further + +- [Build your own Shopping App Example](https://github.com/minio/minio-js-store-app) diff --git a/source/developers/javascript/quickstart.md b/source/developers/javascript/quickstart.md index a2115f17..bebedc7e 100644 --- a/source/developers/javascript/quickstart.md +++ b/source/developers/javascript/quickstart.md @@ -1,177 +1,248 @@ -# MinIO Client SDK for Haskell [![Build Status](https://travis-ci.org/minio/minio-hs.svg?branch=master)](https://travis-ci.org/minio/minio-hs)[![Hackage](https://img.shields.io/hackage/v/minio-hs.svg)](https://hackage.haskell.org/package/minio-hs)[![Slack](https://slack.min.io/slack?type=svg)](https://slack.min.io) +# MinIO JavaScript Library for Amazon S3 Compatible Cloud Storage [![Slack](https://slack.min.io/slack?type=svg)](https://slack.min.io) -The MinIO Haskell Client SDK provides simple APIs to access [MinIO](https://min.io) and Amazon S3 compatible object storage server. +[![NPM](https://nodei.co/npm/minio.png)](https://nodei.co/npm/minio/) -## Minimum Requirements +The MinIO JavaScript Client SDK provides simple APIs to access any Amazon S3 compatible object storage server. -- The Haskell [stack](https://docs.haskellstack.org/en/stable/README/) +This quickstart guide will show you how to install the client SDK and execute an example JavaScript program. For a complete list of APIs and examples, please take a look at the [JavaScript Client API Reference](https://docs.min.io/docs/javascript-client-api-reference) documentation. -## Installation +This document assumes that you have a working [nodejs](http://nodejs.org/) setup in place. -### Add to your project -Simply add `minio-hs` to your project's `.cabal` dependencies section or if you are using hpack, to your `package.yaml` file as usual. - -### Try it out directly with `ghci` - -From your home folder or any non-haskell project directory, just run: +## Download from NPM ```sh - -stack install minio-hs - +npm install --save minio ``` -Then start an interpreter session and browse the available APIs with: +## Download from Source ```sh - -$ stack ghci -> :browse Network.Minio +git clone https://github.com/minio/minio-js +cd minio-js +npm install +npm install -g ``` -## Examples +## Using with TypeScript -The [examples](https://github.com/minio/minio-hs/tree/master/examples) folder contains many examples that you can try out and use to learn and to help with developing your own projects. - -### Quick-Start Example - File Uploader - -This example program connects to a MinIO object storage server, makes a bucket on the server and then uploads a file to the bucket. - -We will use the MinIO server running at https://play.min.io in this example. Feel free to use this service for testing and development. Access credentials are present in the library and are open to the public. - -### FileUploader.hs -``` haskell -#!/usr/bin/env stack --- stack --resolver lts-14.11 runghc --package minio-hs --package optparse-applicative --package filepath - --- --- MinIO Haskell SDK, (C) 2017-2019 MinIO, Inc. --- --- Licensed under the Apache License, Version 2.0 (the "License"); --- you may not use this file except in compliance with the License. --- You may obtain a copy of the License at --- --- http://www.apache.org/licenses/LICENSE-2.0 --- --- Unless required by applicable law or agreed to in writing, software --- distributed under the License is distributed on an "AS IS" BASIS, --- WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. --- See the License for the specific language governing permissions and --- limitations under the License. --- - - -{-# LANGUAGE OverloadedStrings #-} -{-# LANGUAGE ScopedTypeVariables #-} -import Network.Minio - -import Data.Monoid ((<>)) -import Data.Text (pack) -import Options.Applicative -import System.FilePath.Posix -import UnliftIO (throwIO, try) - -import Prelude - --- | The following example uses minio's play server at --- https://play.min.io. The endpoint and associated --- credentials are provided via the libary constant, --- --- > minioPlayCI :: ConnectInfo --- - --- optparse-applicative package based command-line parsing. -fileNameArgs :: Parser FilePath -fileNameArgs = strArgument - (metavar "FILENAME" - <> help "Name of file to upload to AWS S3 or a MinIO server") - -cmdParser = info - (helper <*> fileNameArgs) - (fullDesc - <> progDesc "FileUploader" - <> header - "FileUploader - a simple file-uploader program using minio-hs") - -main :: IO () -main = do - let bucket = "my-bucket" - - -- Parse command line argument - filepath <- execParser cmdParser - let object = pack $ takeBaseName filepath - - res <- runMinio minioPlayCI $ do - -- Make a bucket; catch bucket already exists exception if thrown. - bErr <- try $ makeBucket bucket Nothing - - -- If the bucket already exists, we would get a specific - -- `ServiceErr` exception thrown. - case bErr of - Left BucketAlreadyOwnedByYou -> return () - Left e -> throwIO e - Right _ -> return () - - -- Upload filepath to bucket; object name is derived from filepath. - fPutObject bucket object filepath defaultPutObjectOptions - - case res of - Left e -> putStrLn $ "file upload failed due to " ++ show e - Right () -> putStrLn "file upload succeeded." +```sh +npm install --save-dev @types/minio ``` -### Run FileUploader +## Initialize MinIO Client -``` sh -./FileUploader.hs "path/to/my/file" +You need five items in order to connect to MinIO object storage server. + +| Params | Description | +| :------- | :------------ | +| endPoint | URL to object storage service. | +|port| TCP/IP port number. This input is optional. Default value set to ``80`` for HTTP and ``443`` for HTTPs.| +| accessKey | Access key is like user ID that uniquely identifies your account. | +| secretKey | Secret key is the password to your account. | +|useSSL |Set this value to 'true' to enable secure (HTTPS) access | + + +```js +var Minio = require('minio') + +var minioClient = new Minio.Client({ + endPoint: 'play.min.io', + port: 9000, + useSSL: true, + accessKey: 'Q3AM3UQ867SPQQA43P2F', + secretKey: 'zuf+tfteSlswRu7BJ86wekitnifILbZam1KYY3TG' +}); ``` +## Quick Start Example - File Uploader + +This example program connects to an object storage server, makes a bucket on the server and then uploads a file to the bucket. + +We will use the MinIO server running at [https://play.min.io](https://play.min.io) in this example. Feel free to use this service for testing and development. Access credentials shown in this example are open to the public. + +#### file-uploader.js + +```js +var Minio = require('minio') + +// Instantiate the minio client with the endpoint +// and access keys as shown below. +var minioClient = new Minio.Client({ + endPoint: 'play.min.io', + port: 9000, + useSSL: true, + accessKey: 'Q3AM3UQ867SPQQA43P2F', + secretKey: 'zuf+tfteSlswRu7BJ86wekitnifILbZam1KYY3TG' +}); + +// File that needs to be uploaded. +var file = '/tmp/photos-europe.tar' + +// Make a bucket called europetrip. +minioClient.makeBucket('europetrip', 'us-east-1', function(err) { + if (err) return console.log(err) + + console.log('Bucket created successfully in "us-east-1".') + + var metaData = { + 'Content-Type': 'application/octet-stream', + 'X-Amz-Meta-Testing': 1234, + 'example': 5678 + } + // Using fPutObject API upload your file to the bucket europetrip. + minioClient.fPutObject('europetrip', 'photos-europe.tar', file, metaData, function(err, etag) { + if (err) return console.log(err) + console.log('File uploaded successfully.') + }); +}); +``` + +#### Run file-uploader + +```sh +node file-uploader.js +Bucket created successfully in "us-east-1". + +mc ls play/europetrip/ +[2016-05-25 23:49:50 PDT] 17MiB photos-europe.tar +``` + +## API Reference + +The full API Reference is available here. + +* [Complete API Reference](https://docs.min.io/docs/javascript-client-api-reference) + +### API Reference : Bucket Operations + +* [`makeBucket`](https://docs.min.io/docs/javascript-client-api-reference#makeBucket) +* [`listBuckets`](https://docs.min.io/docs/javascript-client-api-reference#listBuckets) +* [`bucketExists`](https://docs.min.io/docs/javascript-client-api-reference#bucketExists) +* [`removeBucket`](https://docs.min.io/docs/javascript-client-api-reference#removeBucket) +* [`listObjects`](https://docs.min.io/docs/javascript-client-api-reference#listObjects) +* [`listObjectsV2`](https://docs.min.io/docs/javascript-client-api-reference#listObjectsV2) +* [`listObjectsV2WithMetadata`](https://docs.min.io/docs/javascript-client-api-reference#listObjectsV2WithMetadata) (Extension) +* [`listIncompleteUploads`](https://docs.min.io/docs/javascript-client-api-reference#listIncompleteUploads) +* [`getBucketVersioning`](https://docs.min.io/docs/javascript-client-api-reference#getBucketVersioning) +* [`setBucketVersioning`](https://docs.min.io/docs/javascript-client-api-reference#setBucketVersioning) +* [`setBucketLifecycle`](https://docs.min.io/docs/javascript-client-api-reference#setBucketLifecycle) +* [`getBucketLifecycle`](https://docs.min.io/docs/javascript-client-api-reference#getBucketLifecycle) +* [`removeBucketLifecycle`](https://docs.min.io/docs/javascript-client-api-reference#removeBucketLifecycle) +* [`getObjectLockConfig`](https://docs.min.io/docs/javascript-client-api-reference#getObjectLockConfig) +* [`setObjectLockConfig`](https://docs.min.io/docs/javascript-client-api-reference#setObjectLockConfig) + +### API Reference : File Object Operations + +* [`fPutObject`](https://docs.min.io/docs/javascript-client-api-reference#fPutObject) +* [`fGetObject`](https://docs.min.io/docs/javascript-client-api-reference#fGetObject) + +### API Reference : Object Operations + +* [`getObject`](https://docs.min.io/docs/javascript-client-api-reference#getObject) +* [`putObject`](https://docs.min.io/docs/javascript-client-api-reference#putObject) +* [`copyObject`](https://docs.min.io/docs/javascript-client-api-reference#copyObject) +* [`statObject`](https://docs.min.io/docs/javascript-client-api-reference#statObject) +* [`removeObject`](https://docs.min.io/docs/javascript-client-api-reference#removeObject) +* [`removeObjects`](https://docs.min.io/docs/javascript-client-api-reference#removeObjects) +* [`removeIncompleteUpload`](https://docs.min.io/docs/javascript-client-api-reference#removeIncompleteUpload) +* [`selectObjectContent`](https://docs.min.io/docs/javascript-client-api-reference#selectObjectContent) + + +### API Reference : Presigned Operations + +* [`presignedGetObject`](https://docs.min.io/docs/javascript-client-api-reference#presignedGetObject) +* [`presignedPutObject`](https://docs.min.io/docs/javascript-client-api-reference#presignedPutObject) +* [`presignedPostPolicy`](https://docs.min.io/docs/javascript-client-api-reference#presignedPostPolicy) + +### API Reference : Bucket Notification Operations + +* [`getBucketNotification`](https://docs.min.io/docs/javascript-client-api-reference#getBucketNotification) +* [`setBucketNotification`](https://docs.min.io/docs/javascript-client-api-reference#setBucketNotification) +* [`removeAllBucketNotification`](https://docs.min.io/docs/javascript-client-api-reference#removeAllBucketNotification) +* [`listenBucketNotification`](https://docs.min.io/docs/javascript-client-api-reference#listenBucketNotification) (MinIO Extension) + +### API Reference : Bucket Policy Operations + +* [`getBucketPolicy`](https://docs.min.io/docs/javascript-client-api-reference#getBucketPolicy) +* [`setBucketPolicy`](https://docs.min.io/docs/javascript-client-api-reference#setBucketPolicy) + + +## Full Examples + +#### Full Examples : Bucket Operations + +* [list-buckets.js](https://github.com/minio/minio-js/blob/master/examples/list-buckets.js) +* [list-objects.js](https://github.com/minio/minio-js/blob/master/examples/list-objects.js) +* [list-objects-v2.js](https://github.com/minio/minio-js/blob/master/examples/list-objects-v2.js) +* [list-objects-v2-with-metadata.js](https://github.com/minio/minio-js/blob/master/examples/list-objects-v2-with-metadata.js) (Extension) +* [bucket-exists.js](https://github.com/minio/minio-js/blob/master/examples/bucket-exists.js) +* [make-bucket.js](https://github.com/minio/minio-js/blob/master/examples/make-bucket.js) +* [remove-bucket.js](https://github.com/minio/minio-js/blob/master/examples/remove-bucket.js) +* [list-incomplete-uploads.js](https://github.com/minio/minio-js/blob/master/examples/list-incomplete-uploads.js) +* [get-bucket-versioning.js](https://github.com/minio/minio-js/blob/master/examples/get-bucket-versioning.js) +* [set-bucket-versioning.js](https://github.com/minio/minio-js/blob/master/examples/set-bucket-versioning.js) +* [set-bucket-tagging.js](https://github.com/minio/minio-js/blob/master/examples/set-bucket-tagging.js) +* [get-bucket-tagging.js](https://github.com/minio/minio-js/blob/master/examples/get-bucket-tagging.js) +* [remove-bucket-tagging.js](https://github.com/minio/minio-js/blob/master/examples/remove-bucket-tagging.js) +* [set-bucket-lifecycle.js](https://github.com/minio/minio-js/blob/master/examples/set-bucket-lifecycle.js) +* [get-bucket-lifecycle.js](https://github.com/minio/minio-js/blob/master/examples/get-bucket-lifecycle.js) +* [remove-bucket-lifecycle.js](https://github.com/minio/minio-js/blob/master/examples/remove-bucket-lifecycle.js) +* [get-object-lock-config.js](https://github.com/minio/minio-js/blob/master/examples/get-object-lock-config.js) +* [set-object-lock-config.js](https://github.com/minio/minio-js/blob/master/examples/set-object-lock-config.js) +* [set-bucket-replication.js](https://github.com/minio/minio-js/blob/master/examples/set-bucket-replication.js) +* [get-bucket-replication.js](https://github.com/minio/minio-js/blob/master/examples/get-bucket-replication.js) +* [remove-bucket-replication.js](https://github.com/minio/minio-js/blob/master/examples/remove-bucket-replication.js) + +#### Full Examples : File Object Operations +* [fput-object.js](https://github.com/minio/minio-js/blob/master/examples/fput-object.js) +* [fget-object.js](https://github.com/minio/minio-js/blob/master/examples/fget-object.js) + +#### Full Examples : Object Operations +* [put-object.js](https://github.com/minio/minio-js/blob/master/examples/put-object.js) +* [get-object.js](https://github.com/minio/minio-js/blob/master/examples/get-object.js) +* [copy-object.js](https://github.com/minio/minio-js/blob/master/examples/copy-object.js) +* [get-partialobject.js](https://github.com/minio/minio-js/blob/master/examples/get-partialobject.js) +* [remove-object.js](https://github.com/minio/minio-js/blob/master/examples/remove-object.js) +* [remove-incomplete-upload.js](https://github.com/minio/minio-js/blob/master/examples/remove-incomplete-upload.js) +* [stat-object.js](https://github.com/minio/minio-js/blob/master/examples/stat-object.js) +* [get-object-retention.js](https://github.com/minio/minio-js/blob/master/examples/get-object-retention.js) +* [put-object-retention.js](https://github.com/minio/minio-js/blob/master/examples/put-object-retention.js) +* [put-object-tagging.js](https://github.com/minio/minio-js/blob/master/examples/put-object-tagging.js) +* [get-object-tagging.js](https://github.com/minio/minio-js/blob/master/examples/get-object-tagging.js) +* [remove-object-tagging.js](https://github.com/minio/minio-js/blob/master/examples/remove-object-tagging.js) +* [set-object-legal-hold.js](https://github.com/minio/minio-js/blob/master/examples/set-object-legalhold.js) +* [get-object-legal-hold.js](https://github.com/minio/minio-js/blob/master/examples/get-object-legal-hold.js) +* [compose-object.js](https://github.com/minio/minio-js/blob/master/examples/compose-object.js) +* [select-object-content.js](https://github.com/minio/minio-js/blob/master/examples/select-object-content.js) + +#### Full Examples : Presigned Operations +* [presigned-getobject.js](https://github.com/minio/minio-js/blob/master/examples/presigned-getobject.js) +* [presigned-putobject.js](https://github.com/minio/minio-js/blob/master/examples/presigned-putobject.js) +* [presigned-postpolicy.js](https://github.com/minio/minio-js/blob/master/examples/presigned-postpolicy.js) + +#### Full Examples: Bucket Notification Operations +* [get-bucket-notification.js](https://github.com/minio/minio-js/blob/master/examples/get-bucket-notification.js) +* [set-bucket-notification.js](https://github.com/minio/minio-js/blob/master/examples/set-bucket-notification.js) +* [remove-all-bucket-notification.js](https://github.com/minio/minio-js/blob/master/examples/remove-all-bucket-notification.js) +* [listen-bucket-notification.js](https://github.com/minio/minio-js/blob/master/examples/minio/listen-bucket-notification.js) (MinIO Extension) + +#### Full Examples: Bucket Policy Operations +* [get-bucket-policy.js](https://github.com/minio/minio-js/blob/master/examples/get-bucket-policy.js) +* [set-bucket-policy.js](https://github.com/minio/minio-js/blob/master/examples/set-bucket-policy.js) + +## Custom Settings +* [setAccelerateEndPoint](https://github.com/minio/minio-js/blob/master/examples/set-accelerate-end-point.js) + +## Explore Further +* [Complete Documentation](https://docs.min.io) +* [MinIO JavaScript Client SDK API Reference](https://docs.min.io/docs/javascript-client-api-reference) +* [Build your own Shopping App Example- Full Application Example ](https://github.com/minio/minio-js-store-app) + ## Contribute -[Contributors Guide](https://github.com/minio/minio-hs/blob/master/CONTRIBUTING.md) +[Contributors Guide](https://github.com/minio/minio-js/blob/master/CONTRIBUTING.md) -### Development - -To setup: - -```sh -git clone https://github.com/minio/minio-hs.git - -cd minio-hs/ - -stack install -``` - -Tests can be run with: - -```sh - -stack test - -``` - -A section of the tests use the remote MinIO Play server at `https://play.min.io` by default. For library development, using this remote server maybe slow. To run the tests against a locally running MinIO live server at `http://localhost:9000`, just set the environment `MINIO_LOCAL` to any value (and unset it to switch back to Play). - -To run the live server tests, set a build flag as shown below: - -```sh - -stack test --flag minio-hs:live-test - -# OR against a local MinIO server with: - -MINIO_LOCAL=1 stack test --flag minio-hs:live-test - -``` - -The configured CI system always runs both test-suites for every change. - -Documentation can be locally built with: - -```sh - -stack haddock - -``` +[![Build Status](https://travis-ci.org/minio/minio-js.svg)](https://travis-ci.org/minio/minio-js) +[![Build status](https://ci.appveyor.com/api/projects/status/1d05e6nvxcelmrak?svg=true)](https://ci.appveyor.com/project/harshavardhana/minio-js) diff --git a/source/operations/checklists.rst b/source/operations/checklists.rst index a36113e5..6e03ccda 100644 --- a/source/operations/checklists.rst +++ b/source/operations/checklists.rst @@ -15,7 +15,7 @@ These checklists may not meet the precise requirements of your unique deployment |subnet| users can `log in `__ and create a new issue for pre-production deployment reviews. Coordination with MinIO Engineering via SUBNET ensures end-to-end support for performant and reliable deployments. -Community users can seek support on the `MinIO Community Slack `__. +Community users can seek support on the `MinIO Community Slack `__. Community Support is best-effort only and has no SLAs around responsiveness. .. toctree:: diff --git a/source/operations/checklists/hardware.rst b/source/operations/checklists/hardware.rst index d532b80e..7fe1768e 100644 --- a/source/operations/checklists/hardware.rst +++ b/source/operations/checklists/hardware.rst @@ -8,4 +8,249 @@ Hardware Checklist :local: :depth: 2 -Stub - detail Hardware Checklist Items +Use the following checklist when planning the hardware configuration for a production, distributed MinIO deployment. + +Considerations +-------------- + +When selecting hardware for your MinIO implementation, take into account the following factors: + +- Expected amount of data in tebibytes to store at launch +- Expected growth in size of data for at least the next two years +- Number of objects by average object size +- Average retention time of data in years +- Number of sites to be deployed + +Hardware Requirements +--------------------- + +The following checklist provides a minimum hardware specification for production MinIO deployments. +While MinIO can run on commodity or "budget" hardware, we strongly recommend using this table as guidance for best results in production environments. + +.. note:: + + See our `Reference Hardware `__ page for a curated selection of servers and storage components from our hardware partners. + + MinIO does not provide hosted services or hardware sales. + +.. list-table:: + :widths: auto + :width: 100% + + * - :octicon:`circle` + - | Sufficient CPU cores to achieve performance goals for hashing (for example, for healing) and encryption + | MinIO recommends Dual Intel® Xeon® Scalable Gold CPUs (minimum 8 cores per socket) or any CPU with AVX512 instructions + + * - :octicon:`circle` + - | Sufficient RAM to achieve performance goals based on the number of drives and anticipated concurrent requests (see the :ref:`formula and reference table `) + | Refer to the information on :ref:`memory allocation ` for recommended RAM amounts + + * - :octicon:`circle` + - | Four nodes or servers + | For containers or Kubernetes in virtualized environments, MinIO requires four distinct physical nodes. + + * - :octicon:`circle` + - | SATA/SAS drives for capacity and NVMe SSDs for high-performance + | MinIO recommends a minimum of 8 drives per server + + * - :octicon:`circle` + - | 25GbE network for capacity + | 100GbE Network interface cards for high performance + +.. important:: + + The following areas have the greatest impact on MinIO performance, listed in order of importance: + + - Network infrastructure (insufficient or limited throughput) + - Storage controller (old firmware; limited throughput) + - Storage (old firmware; slow, aged, or failing drives) + + Prioritize upgrading these areas before focusing on compute-related performance constraints. + + For example: + + The following examples of network throughput constraints assume spinning disks with ~100MB/S sustained I/O + + - 1GbE network link can support up to 125MB/s, or one spinning disk + - 10GbE network can support approximately 1.25GB/s, potentially supporting 10-12 spinning disk + - 25GbE network can support approximately 3.125GB/s, potentially supporting ~30 disks + + The recommended minimum MinIO cluster of 4 nodes with 4 drives each (16 total disks) requires a 25GbE network to support the total potential aggregate throughput. + For best performance, have a minimum of eight drives per node. + + MinIO takes full advantage of the modern hardware improvements such as AVX-512 SIMD acceleration, 100GbE networking, and NVMe SSDs, when available. + +Recommended Hardware Tests +-------------------------- + +MinIO Diagnostics +~~~~~~~~~~~~~~~~~ + +Run the built in health diagnostic tool. +If you have access to :ref:`SUBNET `, you can upload the results there. + +.. code-block:: shell + :class: copyable + + mc support diag ALIAS --airgap + +Replace ALIAS with the :mc-cmd:`~mc alias` defined for the deployment. + +MinIO Support Diagnostic Tools +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +For deployments registered with MinIO |subnet-short|, you can run the built-in support diagnostic tools. + +Run the three :mc:`mc support perf` tests. + +These server-side tests validate network, drive, and object throughput. +Run all three tests with default options. + +#. Network test + + Run a network throughput test on a cluster with alias ``minio1``. + + .. code-block:: shell + :class: copyable + + mc support perf net minio1 + +#. Drive test + + Run drive read/write performance measurements on all drive on all nodes for a cluster with alias ``minio1``. + The command uses the default blocksize of 4MiB. + + .. code-block:: shell + :class: copyable + + mc support perf drive minio1 + +#. Object test + + Measure the performance of S3 read/write of an object on the alias ``minio1``. + MinIO autotunes concurrency to obtain maximum throughput and IOPS (Input/Output Per Second). + + .. code-block:: shell + :class: copyable + + mc support perf object minio1 + +Operating System Diagnostic Tools +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +If you cannot run the :mc:`mc support diagnostics` or the results show unexpected results, you can use the operating system's default tools. + +Test each drive independently on all servers to ensure they are identical in performance. +Use the results of these OS-level tools to verify the capabilities of your storage hardware. +Record the results for later reference. + +#. Test the drive's performance during write operations + + This tests checks a drive's ability to write new data (uncached) to disk by creating a specified number of blocks at up to a certain number of bytes at a time to mimic how a drive would function with writing uncached data. + This allows you to see the actual drive performance with consistent file I/O. + + .. code-block:: + :class: copyable + + dd if=/dev/zero of=/mnt/driveN/testfile bs=128k count=80000 oflag=direct conv=fdatasync > dd-write-drive1.txt + + Replace ``driveN`` with the path for the disk you are testing. + + .. list-table:: + :widths: auto + :width: 100% + + * - ``dd`` + - The command to copy and paste data. + * - ``if=/dev/zero`` + - Read from ``/dev/zero``, an system-generated endless stream of 0 bytes used to create a file of a specified size + * - ``of=/mnt/driveN/testfile`` + - Write to ``/mnt/driveN/testfile`` + * - ``bs=128k`` + - Write up to 128,000 bytes at a time + * - ``count=80000`` + - Write up to 80000 blocks of data + * - ``oflag=direct`` + - Use direct I/O to write to avoid data from caching + * - ``conv=fdatasync`` + - Physically write output file data before finishing + * - ``> dd-write-drive1.txt`` + - Write the contents of the operation's output to ``dd-write-drive1.txt`` in the current working directory + + The operation returns the number of files written, total size written in bytes, the total length of time for the operation (in seconds), and the speed of the writing in some order of bytes per second. + +#. Test the drive's performance during read operations + + .. code-block:: + :class: copyable + + dd if=/mnt/driveN/testfile of=/dev/null bs=128k iflag=direct > dd-read-drive1.txt + + Replace ``driveN`` with the path for the disk you are testing. + + .. list-table:: + :widths: auto + :width: 100% + + * - ``dd`` + - The command to copy and paste data + * - ``if=/mnt/driveN/testfile`` + - Read from ``/mnt/driveN/testfile``; replace with the path to the file to use for testing the drive's read performance + * - ``of=/dev/null`` + - Write to ``/dev/null``, a virtual file that does not persist after the operation completes + * - ``bs=128k`` + - Write up to 128,000 bytes at a time + * - ``count=80000`` + - Write up to 80000 blocks of data + * - ``iflag=direct`` + - Use direct I/O to read and avoid data from caching + * - ``> dd-read-drive1.txt`` + - Write the contents of the operation's output to ``dd-read-drive1.txt`` in the current working directory + + Use a sufficiently sized file that mimics the primary use case for your deployment to get accurate read test results. + + The following guidelines may help during performance testing: + + - Small files: < 128KB + - Normal files: 128KB – 1GB + - Large files: > 1GB + + You can use the ``head`` command to create a file to use. + The following command example creates a 10 Gigabyte file called ``testfile``. + + .. code-block:: shell + :class: copyable + + head -c 10G testfile + + The operation returns the number of files read, total size read in bytes, the total length of time for the operation (in seconds), and the speed of the reading in bytes per second. + +Third Party Diagnostic Tools +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +IO Controller test + +Use `IOzone `__ to test the input/output controller and all drives in combination. +Document the performance numbers for each server in your deployment. + +.. code-block:: shell + :class: copyable + + iozone -s 1g -r 4m -i 0 -i 1 -i 2 -I -t 160 -F /mnt/sdb1/tmpfile.{1..16} /mnt/sdc1/tmpfile.{1..16} /mnt/sdd1/tmpfile.{1..16} /mnt/sde1/tmpfile.{1..16} /mnt/sdf1/tmpfile.{1..16} /mnt/sdg1/tmpfile.{1..16} /mnt/sdh1/tmpfile.{1..16} /mnt/sdi1/tmpfile.{1..16} /mnt/sdj1/tmpfile.{1..16} /mnt/sdk1/tmpfile.{1..16} > iozone.txt + +.. list-table:: + :widths: auto + :width: 100% + + * - ``-s 1g`` + - Size of 1G per file + * - ``-r`` + - 4m 4MB block size + * - ``-i #`` + - 0=write/rewrite, 1=read/re-read, 2=random-read/write + * - ``-I`` + - Direct-IO modern + * - ``-t N`` + - Number of threads (:math:`numberOfDisks * 16`) + * - ``-F <>`` + - list of files (the above command tests with 16 files per disk) diff --git a/source/operations/checklists/security.rst b/source/operations/checklists/security.rst index 727656ae..9b4278a0 100644 --- a/source/operations/checklists/security.rst +++ b/source/operations/checklists/security.rst @@ -8,4 +8,85 @@ Security Checklist :local: :depth: 2 -Stub - detail Security checklist items +Use the following checklist when planning the security configuration for a production, distributed MinIO deployment. + +Required Steps +-------------- + +.. list-table:: + :widths: auto + :width: 100% + + * - :octicon:`circle` + - Define group policies either on MinIO or the selected 3rd party Identity Provider (LDAP/Active Directory or OpenID) + + * - :octicon:`circle` + - Define individual access policies on MinIO or the selected 3rd party Identity Provider + + * - :octicon:`circle` + - (For Kubernetes deployments only) Configure the tenant(s) to use the selected 3rd party Identity Provider + + +:ref:`Encryption-at-Rest ` +------------------------------------- + +MinIO supports the following external KMS providers through Key Encryption Service (KES): + +- :ref:`Hashicorp Vault Root KMS ` +- :ref:`AWS Root KMS ` +- :ref:`Google Cloud Platform Secret Manager Root KMS ` +- :ref:`Azure Key Vault Root KMS ` + +.. list-table:: + :widths: auto + :width: 100% + + * - :octicon:`circle` + - Download and install the MinIO Key Encryption Service (KES) + + * - :octicon:`circle` + - Enable TLS + + * - :octicon:`circle` + - Generate private and public keys for KES + + * - :octicon:`circle` + - Generate private and public keys for MinIO + + * - :octicon:`circle` + - Create a KES configuration file and start the service + + * - :octicon:`circle` + - Generate an external key for the key management service (KMS) + + * - :octicon:`circle` + - Connect MinIO to the KES + + * - :octicon:`circle` + - Enable server side encryption + + +:ref:`Encryption-in-Transit ("In flight") ` +------------------------------------------------------ + +.. list-table:: + :widths: auto + :width: 100% + + * - :octicon:`circle` + - :ref:`Enable TLS ` + + * - :octicon:`circle` + - Add separate certificates and keys for each internal and external domain that accesses MinIO + + * - :octicon:`circle` + - Generate public and private TLS keys using a supported cipher for TLS 1.3 or TLS 1.2 + + * - :octicon:`circle` + - Configure trusted Certificate Authority (CA) store(s) + + * - :octicon:`circle` + - Expose your Kubernetes service, such as with NGINX + + * - :octicon:`circle` + - (Optional) Validate certificates, such as with https://www.sslchecker.com/certdecoder diff --git a/source/operations/checklists/software.rst b/source/operations/checklists/software.rst index b30bb9f4..3012c92f 100644 --- a/source/operations/checklists/software.rst +++ b/source/operations/checklists/software.rst @@ -8,4 +8,71 @@ Software Checklist :local: :depth: 2 -Stub - detail software checklist items +Use the following checklist when planning the software configuration for a production, distributed MinIO deployment. + +MinIO Pre-requisites +-------------------- + +.. list-table:: + :widths: auto + :width: 100% + + * - :octicon:`circle` + - Servers running a Linux operating system with a 5.x+ kernel, such as Red Hat Enterprise Linux (RHEL) 9 or Ubuntu LTS 20.04+ + + * - :octicon:`circle` + - System administrator access to the remote servers + + * - :octicon:`circle` + - A management tool for distributed systems, such as Ansible, Terraform, or Kubernetes for orchestrated environments. + Kubernetes infrastructures should use the MinIO Operator for best results. + + * - :octicon:`circle` + - Load balancer to handle routing of requests (for example, `NGINX `__) + + * - :octicon:`circle` + - :ref:`Prometheus / Grafana ` setup for monitoring and metrics + + * - :octicon:`circle` + - (optional) :mc:`mc` installed on the local host system + + +MinIO Install +------------- + +See the :ref:`Multi Node Multi Drive deployment guide ` and the :ref:`Minio Tenant deployment guide `. + + +Post Install Tasks +------------------ + +.. list-table:: + :widths: auto + :width: 100% + + + * - :octicon:`circle` + - (optional) Create :mc:`mc alias` for each server from your local machine for command line access to work with the MinIO deployment from a local machine + + * - :octicon:`circle` + - Configure :ref:`Bucket replication ` to duplicate contents of a bucket to another bucket location + + * - :octicon:`circle` + - Configure :ref:`Site replication ` to synchronize contents of multiple dispersed data center locations + + * - :octicon:`circle` + - Configure :ref:`Object retention rules with lifecycle management ` to manage when objects should expire + + * - :octicon:`circle` + - Configure :ref:`Object storage level rules with tiering ` to move objects between hot, warm, and cold storage and maximize storage cost efficiencies + +3rd Party Identity Provider Tasks +--------------------------------- + +.. list-table:: + :widths: auto + :width: 100% + + * - :octicon:`circle` + - | Authenticate to MinIO with :ref:`Security Token Service (STS) ` + | Enabling this requires MinIO support. \ No newline at end of file diff --git a/source/operations/data-recovery.rst b/source/operations/data-recovery.rst index 527096b8..24cfbfc7 100644 --- a/source/operations/data-recovery.rst +++ b/source/operations/data-recovery.rst @@ -57,7 +57,7 @@ write errors. `log in `__ and create a new issue related to drive, node, or site failures. Coordination with MinIO Engineering via SUBNET can ensure successful recovery operations of production MinIO deployments, including root-cause analysis, and health diagnostics. - Community users can seek support on the `MinIO Community Slack `__. + Community users can seek support on the `MinIO Community Slack `__. Community Support is best-effort only and has no SLAs around responsiveness. .. toctree:: diff --git a/source/operations/install-deploy-manage/decommission-server-pool.rst b/source/operations/install-deploy-manage/decommission-server-pool.rst index 0f735d37..fd077665 100644 --- a/source/operations/install-deploy-manage/decommission-server-pool.rst +++ b/source/operations/install-deploy-manage/decommission-server-pool.rst @@ -45,7 +45,7 @@ a :ref:`distributed ` MinIO deployment with diagnostics. Community users can seek support on the `MinIO Community Slack - `__. Community Support is best-effort only and has + `__. Community Support is best-effort only and has no SLAs around responsiveness. .. _minio-decommissioning-prereqs: diff --git a/source/operations/troubleshooting.rst b/source/operations/troubleshooting.rst index 8ea59580..281adc42 100644 --- a/source/operations/troubleshooting.rst +++ b/source/operations/troubleshooting.rst @@ -13,7 +13,7 @@ Overview MinIO users have two options for support. -#. Community support from the `public Slack channel `_. +#. Community support from the `public Slack channel `_. Community support is best-effort only and has no :abbr:`SLA (Service Level Agreement)` or :abbr:`SLO (Service Level Objective)`. #. The MinIO Subscription Network, |subnet-short|, provides either 24 hour or 1 hour :abbr:`SLA (Service Level Agreement)` depending on subscription level. diff --git a/source/reference/minio-mc-admin/mc-admin-decommission.rst b/source/reference/minio-mc-admin/mc-admin-decommission.rst index 2e400761..6ef3a5d4 100644 --- a/source/reference/minio-mc-admin/mc-admin-decommission.rst +++ b/source/reference/minio-mc-admin/mc-admin-decommission.rst @@ -47,7 +47,7 @@ decommissioning a server pool. diagnostics. Community users can seek support on the `MinIO Community Slack - `__. Community Support is best-effort only and has + `__. Community Support is best-effort only and has no SLAs around responsiveness. .. code-block:: shell