minio-hs: A MinIO Haskell Library for Amazon S3 compatible cloud storage.

[ apache, aws, library, network, object-storage ] [ Propose Tags ] [ Report a vulnerability ]

The MinIO Haskell client library provides simple APIs to access MinIO, Amazon S3 and other API compatible cloud storage servers.


[Skip to Readme]

Flags

Manual Flags

NameDescriptionDefault
dev

Build package in development mode

Disabled
live-test

Build the test suite that runs against a live MinIO server

Disabled
examples

Build the examples

Disabled

Use -f <flag> to enable a flag, or -f -<flag> to disable that flag. More info

Downloads

Maintainer's Corner

Package maintainers

For package maintainers and hackage trustees

Candidates

Versions [RSS] 0.0.1, 0.1.0, 0.2.0, 0.2.1, 0.3.0, 0.3.1, 0.3.2, 1.0.0, 1.0.1, 1.1.0, 1.2.0, 1.3.0, 1.3.1, 1.4.0, 1.5.0, 1.5.1, 1.5.2, 1.5.3, 1.6.0, 1.7.0
Change log CHANGELOG.md
Dependencies aeson (>=1.2 && <3), base (>=4.7 && <5), base64-bytestring (>=1.0), binary (>=0.8.5.0), bytestring (>=0.10), case-insensitive (>=1.2), conduit (>=1.3), conduit-extra (>=1.3), connection, cryptonite (>=0.25), cryptonite-conduit (>=0.2), digest (>=0.0.1), directory, filepath (>=1.4), http-client (>=0.5), http-client-tls, http-conduit (>=2.3), http-types (>=0.12), ini, memory (>=0.14), minio-hs, network-uri, optparse-applicative, relude (>=0.7 && <2), resourcet (>=1.2), retry, text (>=1.2), time (>=1.9), time-units (>=1.0.0 && <1.1), transformers (>=0.5), unliftio (>=0.2 && <0.3), unliftio-core (>=0.2 && <0.3), unordered-containers (>=0.2), xml-conduit (>=1.8) [details]
Tested with ghc ==8.6.5, ghc ==8.8.4, ghc ==8.10.7, ghc ==9.0.2, ghc ==9.2.7, ghc ==9.4.5
License Apache-2.0
Author MinIO Dev Team
Maintainer dev@min.io
Category Network, AWS, Object Storage
Home page https://github.com/minio/minio-hs#readme
Source repo head: git clone https://github.com/minio/minio-hs.git
Uploaded by AdityaManthramurthy at 2023-05-22T20:19:31Z
Distributions NixOS:1.7.0
Reverse Dependencies 1 direct, 0 indirect [details]
Executables AssumeRole, SetConfig, ServiceStatus, ServiceSendStop, ServiceSendRestart, ServerInfo, SelectObject, RemoveObject, RemoveIncompleteUpload, RemoveBucket, PutObject, PresignedPutObject, PresignedPostPolicy, PresignedGetObject, MakeBucket, ListObjects, ListIncompleteUploads, ListBuckets, Heal, HeadObject, GetObject, GetConfig, FileUploader, CopyObject, BucketExists
Downloads 10493 total (42 in the last 30 days)
Rating 2.25 (votes: 2) [estimated by Bayesian average]
Your Rating
  • λ
  • λ
  • λ
Status Docs available [build log]
Last success reported on 2023-05-22 [all 1 reports]

Readme for minio-hs-1.7.0

[back to package description]

MinIO Haskell Client SDK for Amazon S3 Compatible Cloud Storage CIHackageSlack

The MinIO Haskell Client SDK provides simple APIs to access MinIO and any Amazon S3 compatible object storage.

This guide assumes that you have a working Haskell development environment.

Installation

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 in a REPL

For a cabal based environment

Download the library source and change to the extracted directory:

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

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

$ cabal repl
ghci> :browse Network.Minio

For a stack based environment

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

stack install minio-hs

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

$ stack ghci
> :browse Network.Minio

Examples

The 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

#!/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."

Run FileUploader

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

Contribute

Contributors Guide

Development

Download the source

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

Build the package:

With cabal:

$ # Configure cabal for development enabling all optional flags defined by the package.
$ cabal configure --enable-tests --test-show-details=direct -fexamples -fdev -flive-test
$ cabal build

With stack:

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

Running tests:

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

With cabal:

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

With stack:

$ export MINIO_LOCAL=1 # to run live tests against local MinIO server
stack test --flag minio-hs:live-test --flag minio-hs:dev

This will run all the test suites.

Building documentation:

$ cabal haddock
$ # OR
$ stack haddock