minio-hs

A Minio Haskell Library for Amazon S3 compatible cloud storage.

https://github.com/minio/minio-hs#readme

Version on this page:1.2.0
LTS Haskell 21.25:1.7.0
Stackage Nightly 2023-06-21:1.7.0
Latest on Hackage:1.7.0

See all snapshots minio-hs appears in

Apache-2.0 licensed by Minio Dev Team
Maintained by [email protected]
This version can be pinned in stack with:minio-hs-1.2.0@sha256:cfd9959fdce7fe26ff81a885f8a5838c3b5e440ee8c8d4bfb1ef6e0b960dc809,9491

Module documentation for 1.2.0

Minio Client SDK for Haskell Build StatusHackageSlack

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

Minimum Requirements

Installation

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

cd minio-hs/

stack install

Tests can be run with:


stack test

A section of the tests use the remote Minio Play server at https://play.minio.io:9000 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).

Documentation can be locally built with:


stack haddock

Quick-Start Example - File Uploader

FileUploader.hs

#!/usr/bin/env stack
-- stack --resolver lts-11.1 runghc --package minio-hs --package optparse-applicative --package filepath

--
-- Minio Haskell SDK, (C) 2017, 2018 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.minio.io:9000.  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
    case bErr of
      Left (MErrService BucketAlreadyOwnedByYou) -> return ()
      Left e                                     -> throwIO e
      Right _                                    -> return ()

    -- Upload filepath to bucket; object is derived from filepath.
    fPutObject bucket object filepath def

  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

Changes

Changelog

Version 1.2.0

  • Export Provider and findFirst to look for credentials (#103)

Version 1.1.0

This version brings the following changes:

  • Adds experimental Admin APIs (#88, #91, #93, #94, #95, #100)
  • Adds support for using Google Compute Storage service when S3 compatibility mode is enabled (#96, #99)

This version also brings some breaking changes (via #101):

  • Adds IsString instance to load server address, and updates initialization API to be more user friendly
  • Drops usage of data-default package and exposes explicit default values for various types used in the library.

Version 1.0.1

This version brings the following (non-breaking) changes:

  • Remove dependency on text-format (#86)
  • Remove direct dependency on exceptions (#87)
  • Adds lower-bounds on dependencies.

Version 1.0.0

This new release changes the following APIs to add new capabilities:

  • Copy Object API now supports more options for source and destination (#73)
  • get/put Object functions now support a wider set of options via a separate settings parameter (#71, #72)
  • getBucketPolicy and setBucketPolicy APIs are added (#82)
  • The library now uses UnliftIO (#83)

Version 0.3.2

This release brings the following changes:

  • Add removeIncompleteUpload API (#49)
  • Add presigned operations APIs (#56)
  • Add presigned Post Policy API (#58)
  • Skip SHA256 checksum header for secure connections (#65)
  • Remove resuming capability in PutObject (#67)
  • Add ListObjectsV1 API support (#66)
  • Add Bucket Notification APIs (#59)
  • Reverse #54 - tests fix.

Version 0.3.1

This is a bug-fix release:

  • Fix concurrency bug in limitedMapConcurrently (#53)
  • Fix tests related to listing incomplete uploads to accommodate Minio server’s changed behaviour to not list incomplete uploads. Note that running these tests against AWS S3 are expected to fail. (#54)

Version 0.3.0

This release includes a breaking change:

Users of the library need not call runResourceT explicitly after calling runMinio. This is now done, within the runMinio call making usage a bit simpler.

Other changes:

  • Export ListUploadsResult and ListObjectsResult (#48)
    • Also take max-keys as an argument for listObjects and max-uploads for listIncompleteUploads.
  • Add bucket and object name validation (#45)
  • Add bucketExists and headBucket APIs (#42)

Version 0.2.1

  • Update dependencies, and switch to Stackage LTS 8.5

Version 0.2.0

This is an interim release which brings some new features. However, the library is not complete and APIs may change.

  • Remove listIncompleteParts API and augment listIncompleteUploads API with information about aggregate size of parts uploaded.
  • Refactors error types and simpler error throwing/handling behaviour.
  • Add removeObject API to delete objects from the service.
  • Rename Network.Minio.getService to Network.Minio.listBuckets.
  • Add docs/API.md and examples directory with comprehensive documentation and examples of high-level APIs exported by the library.
  • Rename types:
    • Rename PartInfo -> PartTuple
    • Rename ListPartInfo -> ObjectPartInfo
  • Add a bucket region cache to avoid locating a bucket’s region for every operation (mainly useful for AWS S3).
  • Add new copyObject API to perform server side object copying.
  • Rename putObjectFromSource API as putObject.
  • Separate out tests into two suites, one with a live-server and the other without any external dependencies.