README.md · typeable/minio-hs

git.iko.soy/typeable/minio-hs

198 lines 6.2 kB history raw

1# MinIO Haskell Client SDK for Amazon S3 Compatible Cloud Storage [![CI](https://github.com/minio/minio-hs/actions/workflows/ci.yml/badge.svg)](https://github.com/minio/minio-hs/actions/workflows/ci.yml)[![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)

3The MinIO Haskell Client SDK provides simple APIs to access [MinIO](https://min.io) and any Amazon S3 compatible object storage.

5This guide assumes that you have a working [Haskell development environment](https://www.haskell.org/downloads/).

7## Installation

9### Add to your project

11Simply add `minio-hs` to your project's `.cabal` dependencies section or if you are using hpack, to your `package.yaml` file as usual.

13### Try it out in a [REPL](https://en.wikipedia.org/wiki/Read%E2%80%93eval%E2%80%93print_loop)

15#### For a cabal based environment

17Download the library source and change to the extracted directory:

19``` sh

20$ cabal get minio-hs

21$ cd minio-hs-1.6.0/ # directory name could be different

22```

24Then load the `ghci` REPL environment with the library and browse the available APIs:

26``` sh

27$ cabal repl

28ghci> :browse Network.Minio

29```

31#### For a stack based environment

33From your home folder or any non-haskell project directory, just run:

35```sh

36stack install minio-hs

37```

39Then start an interpreter session and browse the available APIs with:

41```sh

42$ stack ghci

43> :browse Network.Minio

44```

46## Examples

48The [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.

50### Quick-Start Example - File Uploader

52This example program connects to a MinIO object storage server, makes a bucket on the server and then uploads a file to the bucket.

54We 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.

56### FileUploader.hs

57``` haskell

58#!/usr/bin/env stack

59-- stack --resolver lts-14.11 runghc --package minio-hs --package optparse-applicative --package filepath

61--

63--

64-- Licensed under the Apache License, Version 2.0 (the "License");

65-- you may not use this file except in compliance with the License.

66-- You may obtain a copy of the License at

67--

68-- http://www.apache.org/licenses/LICENSE-2.0

69--

70-- Unless required by applicable law or agreed to in writing, software

71-- distributed under the License is distributed on an "AS IS" BASIS,

72-- WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.

73-- See the License for the specific language governing permissions and

74-- limitations under the License.

75--

78{-# LANGUAGE OverloadedStrings #-}

79{-# LANGUAGE ScopedTypeVariables #-}

80import Network.Minio

82import Data.Monoid ((<>))

83import Data.Text (pack)

84import Options.Applicative

85import System.FilePath.Posix

86import UnliftIO (throwIO, try)

88import Prelude

90-- | The following example uses minio's play server at

91-- https://play.min.io. The endpoint and associated

92-- credentials are provided via the libary constant,

93--

94-- > minioPlayCI :: ConnectInfo

95--

97-- optparse-applicative package based command-line parsing.

98fileNameArgs :: Parser FilePath

99fileNameArgs = strArgument

100 (metavar "FILENAME"

101 <> help "Name of file to upload to AWS S3 or a MinIO server")

102

103cmdParser = info

104 (helper <*> fileNameArgs)

105 (fullDesc

106 <> progDesc "FileUploader"

107 <> header

108 "FileUploader - a simple file-uploader program using minio-hs")

109

110main :: IO ()

111main = do

112 let bucket = "my-bucket"

113

114 -- Parse command line argument

115 filepath <- execParser cmdParser

116 let object = pack $ takeBaseName filepath

117

118 res <- runMinio minioPlayCI $ do

119 -- Make a bucket; catch bucket already exists exception if thrown.

120 bErr <- try $ makeBucket bucket Nothing

121

122 -- If the bucket already exists, we would get a specific

123 -- `ServiceErr` exception thrown.

124 case bErr of

125 Left BucketAlreadyOwnedByYou -> return ()

126 Left e -> throwIO e

127 Right _ -> return ()

128

129 -- Upload filepath to bucket; object name is derived from filepath.

130 fPutObject bucket object filepath defaultPutObjectOptions

131

132 case res of

133 Left e -> putStrLn $ "file upload failed due to " ++ show e

134 Right () -> putStrLn "file upload succeeded."

135```

136

137### Run FileUploader

138

139``` sh

140./FileUploader.hs "path/to/my/file"

141

142```

143

144## Contribute

145

146[Contributors Guide](https://github.com/minio/minio-hs/blob/master/CONTRIBUTING.md)

147

148### Development

149

150#### Download the source

151

152```sh

153$ git clone https://github.com/minio/minio-hs.git

154$ cd minio-hs/

155```

156

157#### Build the package:

158

159With `cabal`:

160

161```sh

162$ # Configure cabal for development enabling all optional flags defined by the package.

163$ cabal configure --enable-tests --test-show-details=direct -fexamples -fdev -flive-test

164$ cabal build

165```

166

167With `stack`:

168

169``` sh

170$ stack build --test --no-run-tests --flag minio-hs:live-test --flag minio-hs:dev --flag minio-hs:examples

171```

172#### Running tests:

173

174A 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` with the credentials `access_key=minio` and `secret_key=minio123`, just set the environment `MINIO_LOCAL` to any value (and unset it to switch back to Play).

175

176With `cabal`:

177

178```sh

179$ export MINIO_LOCAL=1 # to run live tests against local MinIO server

180$ cabal test

181```

182

183With `stack`:

184

185``` sh

186$ export MINIO_LOCAL=1 # to run live tests against local MinIO server