bifrost

README

Bifrost

Rainbow bridge for shipping your files to any cloud storage service with the same function calls.

Table of contents

• Bifrost
• Problem Statement
  • Google Cloud Storage using GCS SDK
  • Pinata Cloud using Pinata API
  • Using Bifrost
• Installation
• Usage
• Contributing
• License
• Changelog
• Contributors

Problem Statement

Many projects need to store files in the cloud and different projects might use different cloud storage providers or, sometimes, multiple cloud providers all at once. Using different SDKs with different implementations for each provider can be tedious and time-consuming. Bifrost aims to simplify the process of working with multiple cloud storage providers by providing a consistent API for all of them.

To gain a better understanding of how Bifrost addresses this issue, let's take you on a ride with Thor by comparing two different code samples for working with Google Cloud Storage and Pinata Cloud in a single project: one using a conventional approach and the other using Bifrost.

Google Cloud Storage using GCS SDK

Without Bifrost, the process of uploading a file to GCS using the Google Cloud Storage client library for Go would typically involve the following steps:

package main

import (
	"context"
	"fmt"
	"io"
	"log"

	"cloud.google.com/go/storage"
)

func main() {
	ctx := context.Background()

	// create a client
	client, err := storage.NewClient(ctx)
	if err != nil {
		log.Fatalf("Failed to create client: %v", err)
	}
	defer client.Close()

	// open the file you want to upload
	file, err := os.Open("path/to/your/file")
	if err != nil {
		log.Fatalf("Failed to open file: %v", err)
	}
	defer file.Close()

	// create a bucket object
	bucket := client.Bucket("your-bucket-name")

	// create an object handle
	object := bucket.Object("destination/file/name")

	// create a writer to upload the file
	writer := object.NewWriter(ctx)

	// copy the contents of the file to the object
	if _, err := io.Copy(writer, file); err != nil {
		log.Fatalf("Failed to upload file: %v", err)
	}

	// close the writer to finalize the upload
	if err := writer.Close(); err != nil {
		log.Fatalf("Failed to close writer: %v", err)
	}

	fmt.Println("File uploaded successfully!")
}

Pinata Cloud using Pinata API

...and for Pinata Cloud, the usual way of uploading a file in Go would be something along the following steps:

package main

import (
	"bytes"
	"fmt"
	"io"
	"io/ioutil"
	"mime/multipart"
	"net/http"
	"os"
)

func main() {
	// Set the API key and secret key
	apiKey := "your-api-key"
	secretApiKey := "your-secret-api-key"

	// Open the file to be uploaded
	file, err := os.Open("path/to/file")
	if err != nil {
		fmt.Println("Error opening file:", err)
		return
	}
	defer file.Close()

	// Prepare the request body
	body := &bytes.Buffer{}
	writer := multipart.NewWriter(body)
	part, err := writer.CreateFormFile("file", file.Name())
	if err != nil {
		fmt.Println("Error creating form file:", err)
		return
	}
	_, err = io.Copy(part, file)
	if err != nil {
		fmt.Println("Error copying file:", err)
		return
	}
	err = writer.Close()
	if err != nil {
		fmt.Println("Error closing writer:", err)
		return
	}

	// Prepare the request
	url := "https://api.pinata.cloud/pinning/pinFileToIPFS"
	req, err := http.NewRequest("POST", url, body)
	if err != nil {
		fmt.Println("Error creating request:", err)
		return
	}
	req.Header.Add("Content-Type", writer.FormDataContentType())
	req.Header.Add("pinata_api_key", apiKey)
	req.Header.Add("pinata_secret_api_key", secretApiKey)

	// Send the request
	client := &http.Client{}
	resp, err := client.Do(req)
	if err != nil {
		fmt.Println("Error sending request:", err)
		return
	}
	defer resp.Body.Close()

	// Read the response body
	respBody, err := ioutil.ReadAll(resp.Body)
	if err != nil {
		fmt.Println("Error reading response:", err)
		return
	}

	// Print the response
	fmt.Println(string(respBody))
}

We can already see the challenges of the conventional methods since they require you to learn to use multiple packages with separate implementation patterns. Now this is why Bifrost comes in! With Bifrost, you can mount rainbow bridges to the providers you want and use the same set of functions to upload files through any of these mounted bridges. This makes it much easier to work with multiple providers and streamlines the development process to just one learning curve.

Now, let's see how we can revamp the two samples above into something much more exciting with Bifrost.

Using Bifrost

package main

import (
	"fmt"
	"os"
	"github.com/opensaucerer/bifrost"
)

// mount a bridge to gcs
gcsBridge, _ := bifrost.NewRainbowBridge(&bifrost.BridgeConfig{
	DefaultBucket:   "bifrost",
	DefaultTimeout:  10,
	Provider:        bifrost.GoogleCloudStorage,
	CredentialsFile: "/path/to/service/account/json", // this is not required if you are using google's default credentials
	EnableDebug:     true,
	PublicRead:      true,
})
defer gcsBridge.Disconnect()
fmt.Printf("Connected to %s\n", gcsBridge.Config().Provider)

// mount a bridge to Pinata
pinataBridge, _ := bifrost.NewRainbowBridge(&bifrost.BridgeConfig{
	Provider:    bifrost.PinataCloud,
	PinataJWT:   os.Getenv("PINATA_JWT"),
	EnableDebug: true,
	PublicRead:  true,
})
defer pinataBridge.Disconnect()
fmt.Printf("Connected to %s\n", pinataBridge.Config().Provider)

// upload a file to gcs using the bridge
guf, _ := gcsBridge.UploadFile(bifrost.File{
	Path:     "../shared/image/aand.png",
	Filename: "a_and_ampersand.png",
	Options: map[string]interface{}{
		bifrost.OptMetadata: map[string]string{
			"originalname": "aand.png",
		},
	},
})
fmt.Printf("Uploaded file %s to GCS at: %s\n", guf.Name, guf.Preview)

// upload a file to Pinata using the bridge
puf, _ := bridge.UploadFile(bifrost.File{
	Path:     "../shared/image/aand.png",
	Filename: "pinata_aand.png",
	Options: map[string]interface{}{
		bifrost.OptPinata: map[string]interface{}{
			"cidVersion": 1,
		},
		bifrost.OptMetadata: map[string]string{
			"originalname": "aand.png",
		},
	},
})
fmt.Printf("Uploaded file %s to Pinata at: %s\n", puf.Name, puf.Preview)

The above example clearly demonstrates the speed, simplicity, and ease of use that Bifrost offers. Now you know what it feels like to ride with Thor!

Installation

To install the Bifrost package, run the following command in your terminal:

go get github.com/opensaucerer/bifrost

Usage

If you want to learn more about how Bifrost is creating different methods to make it easier to use different cloud providers, you can follow these links:

• Google Cloud Storage (GCS)
• Amazon S3
• Pinata Cloud

Variants

Bifrost also exists in other forms and languages and you are free to start a new variant of bifrost in any other form or language of your choice. For now, below are the know variants of bifrost.

• Bifrost CLI
• Bifrost in Python

Contributing

Bifrost is an open source project and we welcome contributions of all kinds. Please read our contributing guide to learn about our development process, how to propose bug fixes and improvements, and how to build and test your changes to Bifrost.

License

Bifrost is MIT licensed.

Changelog

See changelog for more details.

Contributors

Made with contrib.rocks.

Documentation

Overview

package bifrost

provides a rainbow bridge for shipping files to any cloud storage service.

It's like bifrost from marvel comics, but for files.

Index

• Constants
• type BridgeConfig
• type Error
• type File
• type MultiFile
• type PinataPinFileResponse
• type RainbowBridge
  • func NewRainbowBridge(bc *BridgeConfig) (RainbowBridge, error)

Constants

const (
	// WasabiCloudStorage is the identifier of the Wasabi Cloud Storage provider
	WasabiCloudStorage types.Provider = "wasabi"
	// PinataCloud is the identifier of the Pinata Cloud storage
	PinataCloud types.Provider = "pinata"
	// SimpleStorageService is the identifier of the S3 provider
	SimpleStorageService types.Provider = "s3"
	// GoogleCloudStorage is the identifier of the Google Cloud Storage provider
	GoogleCloudStorage types.Provider = "gcs"
)

Misc constants

const (
	// ErrBadRequest is returned when something fails due to client error.
	ErrBadRequest = "bad request"

	// ErrUnauthorized is returned when something fails due to client not being authorized.
	ErrUnauthorized = "unauthorized"

	// ErrInvalidConfig is returned when the config is invalid.
	ErrInvalidConfig = "invalid config"

	// ErrInvalidBucket is returned when the bucket is invalid.
	ErrInvalidBucket = "invalid bucket"

	// ErrInvalidProvider is returned when the provider is invalid.
	ErrInvalidProvider = "invalid provider"

	// ErrInvalidCredentials is returned when the authentication credentials are invalid.
	ErrInvalidCredentials = "invalid credentials"

	// ErrFileOperationFailed is returned when a file operation fails.
	ErrFileOperationFailed = "file operation failed"

	// ErrClientError is returned when the client returns an error.
	ErrClientError = "client error"
)

Error constants.

const (
	// ACL is the option to set the ACL of the file.
	OptACL = "acl"
	// PublicRead is the option to set the ACL of the file to public read.
	ACLPublicRead = "public-read"
	// Private is the option to set the ACL of the file to private.
	ACLPrivate = "private"
	// ContentType is the option to set the content type of the file.
	OptContentType = "content-type"
	// Metadata is the option to set the metadata of the file.
	OptMetadata = "metadata"
	// OptPinata is the option to set the pinataOptions
	OptPinata = "pinataOptions"
)

Options constants.

Types

type BridgeConfig

type BridgeConfig types.BridgeConfig

BridgeConfig is the configuration for the rainbow bridge.

type Error

type Error interface {
	Error() string
	Code() string
}

BifrostError is the interface for errors returned by Bifrost.

type File

type File = types.File

File is the struct for uploading a single file.

type MultiFile

type MultiFile = types.MultiFile

MultiFile is the struct for uploading multiple files. Along with options, you can also set global options that will be applied to all files.

type PinataPinFileResponse

type PinataPinFileResponse = types.PinataPinFileResponse

PinataPinFileResponse is the response from Pinata Cloud when pinning a file.

type RainbowBridge

type RainbowBridge interface {
	/*
		UploadFile uploads a file to the provider storage and returns an error if one occurs.

		Note: for some providers, UploadFile requires that a default bucket be set in bifrost.BridgeConfig.
	*/
	UploadFile(fileFace interface{}) (*types.UploadedFile, error)
	/*
		UploadMultiFile uploads mutliple files to the provider storage and returns an error if one occurs. If any of the uploads fail, the error is appended
		to the []UploadedFile.Error and also logged when debug is enabled while the rest of the uploads continue.

		Note: for some providers, UploadMultiFile requires that a default bucket be set in bifrost.BridgeConfig.
	*/
	UploadMultiFile(multiFace interface{}) ([]*types.UploadedFile, error)
	/*
		Disconnect closes the provider client connection and returns an error if one occurs.

		Disconnect should only be called when the connection is no longer needed.
	*/
	Disconnect() error
	// Config returns the provider configuration.
	Config() *types.BridgeConfig
	// IsConnected returns true if there is an active connection to the provider.
	IsConnected() bool
	/*
		UploadFolder uploads a folder to the provider storage and returns an error if one occurs.

		Note: for some providers, UploadFolder requires that a default bucket be set in bifrost.BridgeConfig.
	*/
	UploadFolder(foldFace interface{}) ([]*types.UploadedFile, error)
}

func NewRainbowBridge

func NewRainbowBridge(bc *BridgeConfig) (RainbowBridge, error)

NewRainbowBridge returns a new Rainbow Bridge for shipping files to your specified cloud storage service.