Skip to content

Commit

Permalink
implement fan-out API (#1826)
Browse files Browse the repository at this point in the history
  • Loading branch information
harshavardhana committed May 19, 2023
1 parent 78f1dd8 commit f62389a
Show file tree
Hide file tree
Showing 3 changed files with 271 additions and 0 deletions.
149 changes: 149 additions & 0 deletions api-put-object-fan-out.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,149 @@
/*
* MinIO Go Library for Amazon S3 Compatible Cloud Storage
* Copyright 2023 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.
*/

package minio

import (
"context"
"encoding/json"
"errors"
"io"
"mime/multipart"
"net/http"
"strconv"
"strings"
"time"
)

// PutObjectFanOutRequest this is the request structure sent
// to the server to fan-out the stream to multiple objects.
type PutObjectFanOutRequest struct {
Key string `json:"key"`
UserMetadata map[string]string `json:"metadata,omitempty"`
UserTags map[string]string `json:"tags,omitempty"`
ContentType string `json:"contentType,omitempty"`
ContentEncoding string `json:"contentEncoding,omitempty"`
ContentDisposition string `json:"contentDisposition,omitempty"`
ContentLanguage string `json:"contentLanguage,omitempty"`
CacheControl string `json:"cacheControl,omitempty"`
Retention RetentionMode `json:"retention,omitempty"`
RetainUntilDate *time.Time `json:"retainUntil,omitempty"`
}

// PutObjectFanOutResponse this is the response structure sent
// by the server upon success or failure for each object
// fan-out keys. Additionally this response carries ETag,
// VersionID and LastModified for each object fan-out.
type PutObjectFanOutResponse struct {
Key string `json:"key"`
ETag string `json:"etag,omitempty"`
VersionID string `json:"versionId,omitempty"`
LastModified *time.Time `json:"lastModified,omitempty"`
Error error `json:"error,omitempty"`
}

// PutObjectFanOut - is a variant of PutObject instead of writing a single object from a single
// stream multiple objects are written, defined via a list of PutObjectFanOutRequests. Each entry
// in PutObjectFanOutRequest carries an object keyname and its relevant metadata if any. `Key` is
// mandatory, rest of the other options in PutObjectFanOutRequest are optional.
func (c *Client) PutObjectFanOut(ctx context.Context, bucket string, body io.Reader, fanOutReq ...PutObjectFanOutRequest) ([]PutObjectFanOutResponse, error) {
if len(fanOutReq) == 0 {
return nil, errInvalidArgument("fan out requests cannot be empty")
}

policy := NewPostPolicy()
policy.SetBucket(bucket)
policy.SetKey(strconv.FormatInt(time.Now().UnixNano(), 16))

// Expires in 15 minutes.
policy.SetExpires(time.Now().UTC().Add(15 * time.Minute))

url, formData, err := c.PresignedPostPolicy(ctx, policy)
if err != nil {
return nil, err
}

r, w := io.Pipe()

req, err := http.NewRequest(http.MethodPost, url.String(), r)
if err != nil {
w.Close()
return nil, err
}

var b strings.Builder
enc := json.NewEncoder(&b)
for _, req := range fanOutReq {
if req.Key == "" {
w.Close()
return nil, errors.New("PutObjectFanOutRequest.Key is mandatory and cannot be empty")
}
if err = enc.Encode(&req); err != nil {
w.Close()
return nil, err
}
}

mwriter := multipart.NewWriter(w)
req.Header.Add("Content-Type", mwriter.FormDataContentType())

go func() {
defer w.Close()
defer mwriter.Close()

for k, v := range formData {
if err := mwriter.WriteField(k, v); err != nil {
return
}
}

if err := mwriter.WriteField("x-minio-fanout-list", b.String()); err != nil {
return
}

mw, err := mwriter.CreateFormFile("file", "fanout-content")
if err != nil {
return
}

if _, err = io.Copy(mw, body); err != nil {
return
}
}()

resp, err := c.do(req)
if err != nil {
return nil, err
}
defer closeResponse(resp)

if resp.StatusCode != http.StatusOK {
return nil, httpRespToErrorResponse(resp, bucket, "fanout-content")
}

dec := json.NewDecoder(resp.Body)
fanOutResp := make([]PutObjectFanOutResponse, 0, len(fanOutReq))
for dec.More() {
var m PutObjectFanOutResponse
if err = dec.Decode(&m); err != nil {
return nil, err
}
fanOutResp = append(fanOutResp, m)
}

return fanOutResp, nil
}
40 changes: 40 additions & 0 deletions docs/API.md
Original file line number Diff line number Diff line change
Expand Up @@ -504,6 +504,46 @@ if err != nil {
}
```

<a name="PutObjectFanOut"></a>
### PutObjectFanOut(ctx context.Context, bucket string, body io.Reader, fanOutReq ...PutObjectFanOutRequest) ([]PutObjectFanOutResponse, error)
A variant of PutObject instead of writing a single object from a single stream multiple objects are written, defined via a list of
*PutObjectFanOutRequest*. Each entry in *PutObjectFanOutRequest* carries an object keyname and its relevant metadata if any.
`Key` is mandatory, rest of the other options in *PutObjectFanOutRequest( are optional.

__Parameters__

| Param | Type | Description |
|:-------------|:---------------------------------|:----------------------------------------------------------------------|
| `ctx` | _context.Context_ | Custom context for timeout/cancellation of the call |
| `bucketName` | _string_ | Name of the bucket |
| `body` | _io.Reader_ | Any Go type that implements io.Reader |
| `fanOutReq` | _[]minio.PutObjectFanOutRequest_ | User input list of all the objects that will be created on the server |

__minio.PutObjectFanOutRequest__

| Field | Type | Description |
|:---------------------|:----------------------|:---------------------------------------------------------------------------------------------------|
| `Key` | _string_ | Name of the object |
| `UserMetadata` | _map[string]string_ | Map of user metadata |
| `UserTags` | _map[string]string_ | Map of user object tags |
| `ContentType` | _string_ | Content type of object, e.g "application/text" |
| `ContentEncoding` | _string_ | Content encoding of object, e.g "gzip" |
| `ContentDisposition` | _string_ | Content disposition of object, "inline" |
| `ContentLanguage` | _string_ | Content language of object, e.g "French" |
| `CacheControl` | _string_ | Used to specify directives for caching mechanisms in both requests and responses e.g "max-age=600" |
| `Retention` | _minio.RetentionMode_ | Retention mode to be set, e.g "COMPLIANCE" |
| `RetainUntilDate` | _time.Time_ | Time until which the retention applied is valid |

__minio.PutObjectFanOutResponse__

| Field | Type | Description |
|:---------------|:-----------|:----------------------------------------------------------------|
| `Key` | _string_ | Name of the object |
| `ETag` | _string_ | ETag opaque unique value of the object |
| `VersionID` | _string_ | VersionID of the uploaded object |
| `LastModified` | _time.Time | Last modified time of the latest object |
| `Error` | _error_ | Is non `nil` only when the fan-out for a specific object failed |

<a name="PutObject"></a>
### PutObject(ctx context.Context, bucketName, objectName string, reader io.Reader, objectSize int64,opts PutObjectOptions) (info UploadInfo, err error)
Uploads objects that are less than 128MiB in a single PUT operation. For objects that are greater than 128MiB in size, PutObject seamlessly uploads the object as parts of 128MiB or more depending on the actual file size. The max upload size for an object is 5TB.
Expand Down
82 changes: 82 additions & 0 deletions examples/minio/put-object-fan-out.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,82 @@
//go:build example
// +build example

/*
* MinIO Go Library for Amazon S3 Compatible Cloud Storage
* Copyright 2023 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.
*/

package main

import (
"context"
"fmt"
"log"
"os"

"github.com/minio/minio-go/v7"
"github.com/minio/minio-go/v7/pkg/credentials"
)

func main() {
const (
// Note: These constants are dummy values,
// please replace them with values for your setup.
YOURACCESSKEYID = "Q3AM3UQ867SPQQA43P2F"
YOURSECRETACCESSKEY = "zuf+tfteSlswRu7BJ86wekitnifILbZam1KYY3TG"
YOURENDPOINT = "play.min.io"
YOURBUCKET = "mybucket" // 'mc mb play/mybucket' if it does not exist.
)

// Requests are always secure (HTTPS) by default. Set secure=false to enable insecure (HTTP) access.
// This boolean value is the last argument for New().

// New returns an Amazon S3 compatible client object. API compatibility (v2 or v4) is automatically
// determined based on the Endpoint value.
minioClient, err := minio.New(YOURENDPOINT, &minio.Options{
Creds: credentials.NewStaticV4(YOURACCESSKEYID, YOURSECRETACCESSKEY, ""),
Secure: true,
})
if err != nil {
log.Fatalln(err)
}

filePath := "my-testfile" // Specify a local file that we will upload

// Open a local file that we will upload
file, err := os.Open(filePath)
if err != nil {
log.Fatalln(err)
}
defer file.Close()

fanOutReq := []minio.PutObjectFanOutRequest{
minio.PutObjectFanOutRequest{Key: "my1-prefix/1.txt"},
minio.PutObjectFanOutRequest{Key: "my1-prefix/2.txt"},
minio.PutObjectFanOutRequest{Key: "my1-prefix/3.txt"},
minio.PutObjectFanOutRequest{Key: "my1-prefix/4.txt"},
minio.PutObjectFanOutRequest{Key: "my1-prefix/5.txt"},
minio.PutObjectFanOutRequest{Key: "my1-prefix/6.txt"},
}

fanOutResp, err := minioClient.PutObjectFanOut(context.Background(), "testbucket", file, fanOutReq...)
if err != nil {
log.Fatalln(err)
}

for _, resp := range fanOutResp {
fmt.Println(resp)
}
}

0 comments on commit f62389a

Please sign in to comment.