minio-hs/docs/API.md

Minio Haskell SDK API Reference

Initialize Minio Client object.

Minio - for public Play server

minioPlayCI :: ConnectInfo
minioPlayCI

AWS S3

awsCI :: ConnectInfo
awsCI { connectAccesskey = "your-access-key"
      , connectSecretkey = "your-secret-key"
      }

Bucket operations	Object Operations
listBuckets	getObject
makeBucket	putObject
removeBucket	fGetObject
listObjects	fPutObject
listObjectsV1	copyObject
listIncompleteUploads	removeObject
bucketExists

1. Connecting and running operations on the storage service

The Haskell Minio SDK provides high-level functionality to perform operations on a Minio server or any AWS S3-like API compatible storage service.

The ConnectInfo type

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.

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.

awsCI :: ConnectInfo

awsCI is a value that provides connection information for AWS S3. Credentials can be supplied by overriding a couple of fields like so:

awsConn = awsCI {
    connectAccessKey = "my-AWS-access-key"
  , connectSecretKey = "my-AWS-secret-key"
  }

awsWithRegionCI :: Region -> Bool -> ConnectInfo

This constructor allows to specify the initial region and a Boolean to enable/disable the automatic region discovery behaviour.

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.minio.io:9000/.

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:

{-# 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."

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

listBuckets :: Minio [BucketInfo]

Lists 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
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.

Example

{-# 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

{-# 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."

listObjects :: Bucket -> Maybe Text -> Bool -> C.Producer Minio ObjectInfo

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.Producer Minio ObjectInfo	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

{-# Language OverloadedStrings #-}

import Data.Conduit (($$))
import Conduit.Combinators (sinkList)

main :: IO ()
main = do
  let
    bucket = "test"

  -- Performs a recursive listing of all objects under bucket "test"
  -- on play.minio.io.
  res <- runMinio minioPlayCI $ do
    listObjects bucket Nothing True $$ sinkList
  print res

listObjectsV1 :: Bucket -> Maybe Text -> Bool -> C.Producer Minio ObjectInfo

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.Producer Minio ObjectInfo	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

{-# Language OverloadedStrings #-}

import Data.Conduit (($$))
import Conduit.Combinators (sinkList)

main :: IO ()
main = do
  let
    bucket = "test"

  -- Performs a recursive listing of all objects under bucket "test"
  -- on play.minio.io.
  res <- runMinio minioPlayCI $ do
    listObjectsV1 bucket Nothing True $$ sinkList
  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.Producer Minio UploadInfo	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

{-# Language OverloadedStrings #-}

import Data.Conduit (($$))
import Conduit.Combinators (sinkList)

main :: IO ()
main = do
  let
    bucket = "test"

  -- Performs a recursive listing of all incompletely uploaded objects
  -- under bucket "test" on play.minio.io.
  res <- runMinio minioPlayCI $ do
    listIncompleteUploads bucket Nothing True $$ sinkList
  print res

3. Object operations

getObject :: Bucket -> Object -> Minio (C.ResumableSource Minio ByteString)

Get an object from the service.

Parameters

In the expression getObject 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

Return Value

The return value can be incrementally read to process the contents of the object.

Return type	Description
C.ResumableSource Minio ByteString	A Conduit ResumableSource of ByteString values.

Example

{-# Language OverloadedStrings #-}

import Network.Minio
import Data.Conduit (($$+-))
import Data.Conduit.Binary (sinkLbs)
import qualified Data.ByteString.Lazy as LB

main :: IO ()
main = do
  let
    bucket = "mybucket"
    object = "myobject"

  -- Lists the parts in an incompletely uploaded object identified by
  -- bucket, object and upload ID.
  res <- runMinio minioPlayCI $ do
           source <- getObject bucket object
           source $$+- sinkLbs

  -- the following the prints the contents of the object.
  putStrLn $ either
    (("Failed to getObject: " ++) . show)
    (("Read an object of length: " ++) . show . LB.length)
    res

putObject :: Bucket -> Object -> C.Producer Minio ByteString -> Maybe Int64 -> Minio ()

Uploads an object to a bucket in the service, from the given input byte stream of optionally supplied length

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.Producer Minio ByteString	A Conduit Producer of ByteString values

Example

{-# Language OverloadedStrings #-}
import Network.Minio
import qualified Data.Conduit.Combinators as CC

main :: IO ()
main = do
  let
    bucket = "mybucket"
    object = "myobject"
    kb15 = 15 * 1024

  res <- runMinio minioPlayCI $ do
           putObject bucket object (CC.repeat "a") (Just kb15)

  case res of
    Left e -> putStrLn $ "Failed to putObject " ++ show bucket ++ "/" ++ show object
    Right _ -> putStrLn "PutObject was successful"

fGetObject :: Bucket -> Object -> FilePath -> 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

{-# Language OverloadedStrings #-}
import Network.Minio

import Data.Conduit (($$+-))
import Data.Conduit.Binary (sinkLbs)
import Prelude

-- | The following example uses minio's play server at
-- https://play.minio.io:9000.  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
    (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

{-# 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 :: Bucket -> Object -> CopyPartSource -> Minio ()

Copies content of an object from the service to another

Parameters

In the expression copyObject bucketName objectName cps the parameters are:

Param	Type	Description
bucketName	Bucket (alias for Text)	Name of the bucket
objectName	Object (alias for Text)	Name of the object
cps	CopyPartSource	A value representing properties of the source object

CopyPartSource record type

Field	Type	Description
cpSource	Text	Name of source object formatted as "/srcBucket/srcObject"
cpSourceRange	Maybe (Int64, Int64)	Represents the byte range of source object. (0, 9) represents first ten bytes of source object
cpSourceIfMatch	Maybe Text	(Optional) ETag source object should match
cpSourceIfNoneMatch	Maybe Text	(Optional) ETag source object shouldn't match
cpSourceIfUnmodifiedSince	Maybe UTCTime	(Optional) Time since source object wasn't modified
cpSourceIfModifiedSince	Maybe UTCTime	(Optional) Time since source object was modified

Example

{-# Language OverloadedStrings #-}
import Network.Minio

main :: IO ()
main = do
  let
    bucket = "mybucket"
    object = "myobject"
    srcObject = "/mybucket/srcObject"

  res <- runMinio minioPlayCI $ do
           copyObject bucket object def { cpSource = srcObject }

  case res of
    Left e -> putStrLn $ "Failed to copyObject " ++ show srcObject"
    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

{-# 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

{-# 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"

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