From 0437483e99e80825c178a582050a32a2a2a8d6fb Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" Date: Tue, 7 Jan 2025 19:07:59 +0000 Subject: [PATCH] Sync docs for release https://github.com/gofiber/storage/releases/tag/valkey/v0.1.0 --- .../version-valkey_v0.x.x/README.md | 78 ++++++ .../version-valkey_v0.x.x/arangodb/README.md | 120 ++++++++++ .../version-valkey_v0.x.x/azureblob/README.md | 112 +++++++++ .../version-valkey_v0.x.x/badger/README.md | 119 ++++++++++ .../version-valkey_v0.x.x/bbolt/README.md | 104 ++++++++ .../clickhouse/README.md | 123 ++++++++++ .../cloudflarekv/README.md | 114 +++++++++ .../version-valkey_v0.x.x/coherence/README.md | 138 +++++++++++ .../version-valkey_v0.x.x/couchbase/README.md | 94 ++++++++ .../version-valkey_v0.x.x/dynamodb/README.md | 143 +++++++++++ .../version-valkey_v0.x.x/etcd/README.md | 87 +++++++ .../version-valkey_v0.x.x/memcache/README.md | 82 +++++++ .../version-valkey_v0.x.x/memory/README.md | 79 +++++++ .../version-valkey_v0.x.x/minio/README.md | 142 +++++++++++ .../mockstorage/README.md | 171 ++++++++++++++ .../version-valkey_v0.x.x/mongodb/README.md | 128 ++++++++++ .../version-valkey_v0.x.x/mssql/README.md | 146 ++++++++++++ .../version-valkey_v0.x.x/mysql/README.md | 146 ++++++++++++ .../version-valkey_v0.x.x/nats/README.md | 112 +++++++++ .../version-valkey_v0.x.x/pebble/README.md | 94 ++++++++ .../version-valkey_v0.x.x/postgres/README.md | 137 +++++++++++ .../version-valkey_v0.x.x/redis/README.md | 196 ++++++++++++++++ .../version-valkey_v0.x.x/ristretto/README.md | 86 +++++++ .../version-valkey_v0.x.x/rueidis/README.md | 212 +++++++++++++++++ .../version-valkey_v0.x.x/s3/README.md | 163 +++++++++++++ .../version-valkey_v0.x.x/scylladb/README.md | 183 +++++++++++++++ .../version-valkey_v0.x.x/sqlite3/README.md | 121 ++++++++++ .../version-valkey_v0.x.x/valkey/README.md | 222 ++++++++++++++++++ .../version-valkey_v0.x.x-sidebars.json | 8 + storage_versions.json | 1 + 30 files changed, 3661 insertions(+) create mode 100644 storage_versioned_docs/version-valkey_v0.x.x/README.md create mode 100644 storage_versioned_docs/version-valkey_v0.x.x/arangodb/README.md create mode 100644 storage_versioned_docs/version-valkey_v0.x.x/azureblob/README.md create mode 100644 storage_versioned_docs/version-valkey_v0.x.x/badger/README.md create mode 100644 storage_versioned_docs/version-valkey_v0.x.x/bbolt/README.md create mode 100644 storage_versioned_docs/version-valkey_v0.x.x/clickhouse/README.md create mode 100644 storage_versioned_docs/version-valkey_v0.x.x/cloudflarekv/README.md create mode 100644 storage_versioned_docs/version-valkey_v0.x.x/coherence/README.md create mode 100644 storage_versioned_docs/version-valkey_v0.x.x/couchbase/README.md create mode 100644 storage_versioned_docs/version-valkey_v0.x.x/dynamodb/README.md create mode 100644 storage_versioned_docs/version-valkey_v0.x.x/etcd/README.md create mode 100644 storage_versioned_docs/version-valkey_v0.x.x/memcache/README.md create mode 100644 storage_versioned_docs/version-valkey_v0.x.x/memory/README.md create mode 100644 storage_versioned_docs/version-valkey_v0.x.x/minio/README.md create mode 100644 storage_versioned_docs/version-valkey_v0.x.x/mockstorage/README.md create mode 100644 storage_versioned_docs/version-valkey_v0.x.x/mongodb/README.md create mode 100644 storage_versioned_docs/version-valkey_v0.x.x/mssql/README.md create mode 100644 storage_versioned_docs/version-valkey_v0.x.x/mysql/README.md create mode 100644 storage_versioned_docs/version-valkey_v0.x.x/nats/README.md create mode 100644 storage_versioned_docs/version-valkey_v0.x.x/pebble/README.md create mode 100644 storage_versioned_docs/version-valkey_v0.x.x/postgres/README.md create mode 100644 storage_versioned_docs/version-valkey_v0.x.x/redis/README.md create mode 100644 storage_versioned_docs/version-valkey_v0.x.x/ristretto/README.md create mode 100644 storage_versioned_docs/version-valkey_v0.x.x/rueidis/README.md create mode 100644 storage_versioned_docs/version-valkey_v0.x.x/s3/README.md create mode 100644 storage_versioned_docs/version-valkey_v0.x.x/scylladb/README.md create mode 100644 storage_versioned_docs/version-valkey_v0.x.x/sqlite3/README.md create mode 100644 storage_versioned_docs/version-valkey_v0.x.x/valkey/README.md create mode 100644 storage_versioned_sidebars/version-valkey_v0.x.x-sidebars.json diff --git a/storage_versioned_docs/version-valkey_v0.x.x/README.md b/storage_versioned_docs/version-valkey_v0.x.x/README.md new file mode 100644 index 00000000000..79d51567024 --- /dev/null +++ b/storage_versioned_docs/version-valkey_v0.x.x/README.md @@ -0,0 +1,78 @@ +--- +title: 👋 Welcome +description: 📦 Premade storage drivers for 🚀 Fiber. +sidebar_position: 1 +--- + +

+ Fiber + Fiber +
+ + + + + + + + + + +

+ +Premade storage drivers that implement the [`Storage`](https://github.com/gofiber/storage/blob/main/storage.go) interface, designed to be used with various [Fiber middlewares](https://github.com/gofiber/fiber/tree/master/middleware). + +```go +// Storage interface for communicating with different database/key-value +// providers. Visit https://github.com/gofiber/storage for more info. +type Storage interface { + // Get gets the value for the given key. + // `nil, nil` is returned when the key does not exist + Get(key string) ([]byte, error) + + // Set stores the given value for the given key along + // with an expiration value, 0 means no expiration. + // Empty key or value will be ignored without an error. + Set(key string, val []byte, exp time.Duration) error + + // Delete deletes the value for the given key. + // It returns no error if the storage does not contain the key, + Delete(key string) error + + // Reset resets the storage and delete all keys. + Reset() error + + // Close closes the storage and will stop any running garbage + // collectors and open connections. + Close() error +} +``` + +## 📑 Storage Implementations + +- [ArangoDB](./arangodb/README.md) +- [AzureBlob](./azureblob/README.md) +- [Badger](./badger/README.md) +- [Bbolt](./bbolt) +- [CloudflareKV](./cloudflarekv/README.md) +- [Coherence](./coherence/README.md) +- [Couchbase](./couchbase/README.md) +- [DynamoDB](./dynamodb/README.md) +- [Etcd](./etcd/README.md) +- [Memcache](./memcache/README.md) +- [Memory](./memory/README.md) +- [Minio](./minio/README.md) +- [MockStorage](./mockstorage/README.md) +- [MongoDB](./mongodb/README.md) +- [MSSQL](./mssql/README.md) +- [MySQL](./mysql/README.md) +- [NATS](./nats/README.md) +- [Pebble](./pebble/README.md) +- [Postgres](./postgres/README.md) +- [Redis](./redis/README.md) +- [Rueidis](./rueidis/README.md) +- [S3](./s3/README.md) +- [ScyllaDB](./scylladb/README.md) +- [SQLite3](./sqlite3/README.md) +- [ClickHouse](./clickhouse/README.md) +- [Valkey](./valkey/README.md) diff --git a/storage_versioned_docs/version-valkey_v0.x.x/arangodb/README.md b/storage_versioned_docs/version-valkey_v0.x.x/arangodb/README.md new file mode 100644 index 00000000000..8478d2c170a --- /dev/null +++ b/storage_versioned_docs/version-valkey_v0.x.x/arangodb/README.md @@ -0,0 +1,120 @@ +--- +id: arangodb +title: ArangoDB +--- + +![Release](https://img.shields.io/github/v/tag/gofiber/storage?filter=arangodb*) +[![Discord](https://img.shields.io/discord/704680098577514527?style=flat&label=%F0%9F%92%AC%20discord&color=00ACD7)](https://gofiber.io/discord) +![Test](https://img.shields.io/github/actions/workflow/status/gofiber/storage/test-arangodb.yml?label=Tests) +![Security](https://img.shields.io/github/actions/workflow/status/gofiber/storage/gosec.yml?label=Security) +![Linter](https://img.shields.io/github/actions/workflow/status/gofiber/storage/linter.yml?label=Linter) + +A ArangoDB storage driver using `arangodb/go-driver` and [arangodb/go-driver](https://github.com/arangodb/go-driver). + +**Note: Requires Go 1.19 and above** + +### Table of Contents +- [Signatures](#signatures) +- [Installation](#installation) +- [Examples](#examples) +- [Config](#config) +- [Default Config](#default-config) + +### Signatures +```go +func New(config ...Config) Storage +func (s *Storage) Get(key string) ([]byte, error) +func (s *Storage) Set(key string, val []byte, exp time.Duration) error +func (s *Storage) Delete(key string) error +func (s *Storage) Reset() error +func (s *Storage) Close() error +func (s *Storage) Conn() driver.Client +``` +### Installation +ArangoDB is tested on the 2 last (1.14/1.15) [Go versions](https://golang.org/dl/) with support for modules. So make sure to initialize one first if you didn't do that yet: +```bash +go mod init github.com// +``` +And then install the mysql implementation: +```bash +go get github.com/gofiber/storage/arangodb/v2 +``` + +### Examples +Import the storage package. +```go +import "github.com/gofiber/storage/arangodb/v2" +``` + +You can use the following possibilities to create a storage: +```go +// Initialize default config +store := arangodb.New() + +// Initialize custom config +store := arangodb.New(arangodb.Config{ + Host: "http://127.0.0.1", + Port: 8529, + Database: "fiber", + Collection: "fiber_storage", + Reset: false, + GCInterval: 10 * time.Second, +}) +``` + +### Config +```go +type Config struct { + // Host name where the DB is hosted + // + // Optional. Default is "http://127.0.0.1" + Host string + + // Port where the DB is listening on + // + // Optional. Default is 8529 + Port int + + // Server username + // + // Optional. Default is "" + Username string + + // Server password + // + // Optional. Default is "" + Password string + + // Database name + // + // Optional. Default is "fiber" + Database string + + // Collection name + // + // Optional. Default is "fiber_storage" + Collection string + + // Reset clears any existing keys in existing collection + // + // Optional. Default is false + Reset bool + // Time before deleting expired keys + // + // Optional. Default is 10 * time.Second + GCInterval time.Duration +} +``` + +### Default Config +Used only for optional fields +```go +var ConfigDefault = Config{ + Host: "http://127.0.0.1", + Port: 8529, + Database: "fiber", + Collection: "fiber_storage", + Reset: false, + GCInterval: 10 * time.Second, +} +``` diff --git a/storage_versioned_docs/version-valkey_v0.x.x/azureblob/README.md b/storage_versioned_docs/version-valkey_v0.x.x/azureblob/README.md new file mode 100644 index 00000000000..f5c216b1303 --- /dev/null +++ b/storage_versioned_docs/version-valkey_v0.x.x/azureblob/README.md @@ -0,0 +1,112 @@ +--- +id: azureblob +title: Azure Blob +--- + +![Release](https://img.shields.io/github/v/tag/gofiber/storage?filter=azureblob*) +[![Discord](https://img.shields.io/discord/704680098577514527?style=flat&label=%F0%9F%92%AC%20discord&color=00ACD7)](https://gofiber.io/discord) +![Test](https://img.shields.io/github/actions/workflow/status/gofiber/storage/test-azureblob.yml?label=Tests) +![Security](https://img.shields.io/github/actions/workflow/status/gofiber/storage/gosec.yml?label=Security) +![Linter](https://img.shields.io/github/actions/workflow/status/gofiber/storage/linter.yml?label=Linter) + +[Azure Blob storage](https://azure.microsoft.com/en-us/products/storage/blobs/#overview) is Microsoft's object storage solution for the cloud. + +**Note: Requires Go 1.19 and above** + +### Table of Contents + +- [Signatures](#signatures) +- [Installation](#installation) +- [Examples](#examples) +- [Config](#config) +- [Default Config](#default-config) + +### Signatures + +```go +func New(config ...Config) Storage +func (s *Storage) Get(key string) ([]byte, error) +func (s *Storage) Set(key string, val []byte, exp time.Duration) error +func (s *Storage) Delete(key string) error +func (s *Storage) Reset() error +func (s *Storage) Close() error +func (s *Storage) Conn() *azblob.Client +``` + +### Installation + +Azure blob storage driver is tested on the 2 last [Go versions](https://golang.org/dl/) with support for modules. So make sure to initialize one first if you didn't do that yet: + +```bash +go mod init github.com// +``` + +And then install the azure blob implementation: + +```bash +go get github.com/gofiber/storage/azureblob/v2 +``` + +### Examples + +Import the storage package. + +```go +import "github.com/gofiber/storage/azureblob/v2" +``` + +You can use the following possibilities to create a storage: + +```go +// Initialize default config +store := azureblob.New() + +// Initialize custom config +store := azureblob.New(azureblob.Config{ + Account: "test", + Container: "test", + Credentials: Credentials{ + Account: "test", + Key: "YXp1cml0ZWtleQo=", + }, +}) +``` + +### Config + +```go +type Config struct { + // Storage account name. + Account string + // Container name. + Container string + // Storage endpoint. + // Optional. Default: "https://STORAGEACCOUNTNAME.blob.core.windows.net" + Endpoint string + // Request timeout. + // Optional. Default is 0 (no timeout) + RequestTimeout time.Duration + // Reset clears any existing keys in existing container. + // Optional. Default is false + Reset bool + // Credentials overrides AWS access key and AWS secret access key. Not recommended. + // Optional. Default is Credentials{} + Credentials Credentials + // The maximum number of times requests that encounter retryable failures should be attempted. + // Optional. Default is 3 + MaxAttempts int +} +``` + +### Default Config + +```go +var ConfigDefault = Config{ + Account: "", + Container: "", + Endpoint: "", + RequestTimeout: 0, + Reset: false, + MaxAttempts: 3, +} +``` diff --git a/storage_versioned_docs/version-valkey_v0.x.x/badger/README.md b/storage_versioned_docs/version-valkey_v0.x.x/badger/README.md new file mode 100644 index 00000000000..45706558e57 --- /dev/null +++ b/storage_versioned_docs/version-valkey_v0.x.x/badger/README.md @@ -0,0 +1,119 @@ +--- +id: badger +title: Badger +--- + +![Release](https://img.shields.io/github/v/tag/gofiber/storage?filter=badger*) +[![Discord](https://img.shields.io/discord/704680098577514527?style=flat&label=%F0%9F%92%AC%20discord&color=00ACD7)](https://gofiber.io/discord) +![Test](https://img.shields.io/github/actions/workflow/status/gofiber/storage/test-badger.yml?label=Tests) +![Security](https://img.shields.io/github/actions/workflow/status/gofiber/storage/gosec.yml?label=Security) +![Linter](https://img.shields.io/github/actions/workflow/status/gofiber/storage/linter.yml?label=Linter) + +A fast key-value DB using [dgraph-io/badger](https://github.com/dgraph-io/badger) + +**Note: Requires Go 1.19 and above** + +### Table of Contents + +- [Signatures](#signatures) +- [Installation](#installation) +- [Examples](#examples) +- [Config](#config) +- [Default Config](#default-config) + +### Signatures + +```go +func New(config ...Config) Storage +func (s *Storage) Get(key string) ([]byte, error) +func (s *Storage) Set(key string, val []byte, exp time.Duration) error +func (s *Storage) Delete(key string) error +func (s *Storage) Reset() error +func (s *Storage) Close() error +func (s *Storage) Conn() *badger.DB +``` + +### Installation + +Badger is tested on the 2 last [Go versions](https://golang.org/dl/) with support for modules. So make sure to initialize one first if you didn't do that yet: + +```bash +go mod init github.com// +``` + +And then install the badger implementation: + +```bash +go get github.com/gofiber/storage/badger/v2 +``` + +### Examples + +Import the storage package. + +```go +import "github.com/gofiber/storage/badger/v2" +``` + +You can use the following possibilities to create a storage: + +```go +// Initialize default config +store := badger.New() + +// Initialize custom config +store := badger.New(badger.Config{ + Database: "./fiber.badger", + Reset: false, + GCInterval: 10 * time.Second, +}) +``` + +### Config + +```go +type Config struct { + // Database name + // + // Optional. Default is "./fiber.badger" + Database string + + // Reset clears any existing keys in existing Table + // + // Optional. Default is false + Reset bool + + // Time before deleting expired keys + // + // Optional. Default is 10 * time.Second + GCInterval time.Duration + + // BadgerOptions is a way to set options in badger + // + // Optional. Default is badger.DefaultOptions("./fiber.badger") + BadgerOptions badger.Options + + // Logger is the default logger used by badger + // + // Optional. Default is nil + Logger badger.Logger + + // UseLogger define if any logger will be used + // + // Optional. Default is false + UseLogger bool +} +``` + +### Default Config + +```go +var ConfigDefault = Config{ + Database: "./fiber.badger", + Reset: false, + GCInterval: 10 * time.Second, + BadgerOptions: badger.DefaultOptions("./fiber.badger").WithLogger(nil), + Logger: nil, + UseLogger: false, +} +``` diff --git a/storage_versioned_docs/version-valkey_v0.x.x/bbolt/README.md b/storage_versioned_docs/version-valkey_v0.x.x/bbolt/README.md new file mode 100644 index 00000000000..aeacbb73487 --- /dev/null +++ b/storage_versioned_docs/version-valkey_v0.x.x/bbolt/README.md @@ -0,0 +1,104 @@ +--- +id: bbolt +title: Bbolt +--- + +![Release](https://img.shields.io/github/v/tag/gofiber/storage?filter=bbolt*) +[![Discord](https://img.shields.io/discord/704680098577514527?style=flat&label=%F0%9F%92%AC%20discord&color=00ACD7)](https://gofiber.io/discord) +![Test](https://img.shields.io/github/actions/workflow/status/gofiber/storage/test-bbolt.yml?label=Tests) +![Security](https://img.shields.io/github/actions/workflow/status/gofiber/storage/gosec.yml?label=Security) +![Linter](https://img.shields.io/github/actions/workflow/status/gofiber/storage/linter.yml?label=Linter) + +A Bbolt storage driver using [etcd-io/bbolt](https://github.com/etcd-io/bbolt). Bolt is a pure Go key/value store inspired by [Howard Chu's](https://twitter.com/hyc_symas) [LMDB project](https://www.symas.com/symas-embedded-database-lmdb). The goal of the project is to provide a simple, fast, and reliable database for projects that don't require a full database server such as Postgres or MySQL. + +**Note: Requires Go 1.19 and above** + +### Table of Contents +- [Signatures](#signatures) +- [Installation](#installation) +- [Examples](#examples) +- [Config](#config) +- [Default Config](#default-config) + +### Signatures +```go +func New(config ...Config) Storage +func (s *Storage) Get(key string) ([]byte, error) +func (s *Storage) Set(key string, val []byte, exp time.Duration) error +func (s *Storage) Delete(key string) error +func (s *Storage) Reset() error +func (s *Storage) Close() error +func (s *Storage) Conn() *bbolt.DB +``` +### Installation +Bbolt is tested on the 2 last [Go versions](https://golang.org/dl/) with support for modules. So make sure to initialize one first if you didn't do that yet: +```bash +go mod init github.com// +``` +And then install the s3 implementation: +```bash +go get github.com/gofiber/storage/bbolt/v2 +``` + +### Examples +Import the storage package. +```go +import "github.com/gofiber/storage/bbolt/v2" +``` + +You can use the following possibilities to create a storage: +```go +// Initialize default config +store := bbolt.New() + +// Initialize custom config +store := bbolt.New(bbolt.Config{ + Database: "my_database.db", + Bucket: "my-bucket", + Reset: false, +}) +``` + +### Config +```go +// Config defines the config for storage. +type Config struct { + // Database path + // + // Optional. Default is "fiber.db" + Database string + + // Bbolt bucket name + // + // Optional. Default is "fiber_storage" + Bucket string + + // Timeout is the amount of time to wait to obtain a file lock. + // Only available on Darwin and Linux. + // + // Optional. Default is 60 * time.Second. + Timeout time.Duration + + // Open database in read-only mode. + // + // Optional. Default is false + ReadOnly bool + + // Reset clears any existing keys in existing Bucket + // + // Optional. Default is false + Reset bool +} +``` + +### Default Config +```go +// ConfigDefault is the default config +var ConfigDefault = Config{ + Database: "fiber.db", + Bucket: "fiber_storage", + Timeout: 60 * time.Second, + ReadOnly: false, + Reset: false, +} +``` diff --git a/storage_versioned_docs/version-valkey_v0.x.x/clickhouse/README.md b/storage_versioned_docs/version-valkey_v0.x.x/clickhouse/README.md new file mode 100644 index 00000000000..8efab4d732b --- /dev/null +++ b/storage_versioned_docs/version-valkey_v0.x.x/clickhouse/README.md @@ -0,0 +1,123 @@ +# Clickhouse + +A Clickhouse storage driver using [https://github.com/ClickHouse/clickhouse-go](https://github.com/ClickHouse/clickhouse-go). + +### Table of Contents + +- [Signatures](#signatures) +- [Installation](#installation) +- [Examples](#examples) +- [Config](#config) +- [Default Config](#default-config) + +### Signatures + +```go +func New(config ...Config) (*Storage, error) +func (s *Storage) Get(key string) ([]byte, error) +func (s *Storage) Set(key string, val []byte, exp time.Duration) error +func (s *Storage) Delete(key string) error +func (s *Storage) Reset() error +func (s *Storage) Close() error +func (s *Storage) Conn() *Session +``` + +### Installation + +Clickhouse is supported on the latest two versions of Go: + +Install the clickhouse implementation: +```bash +go get github.com/gofiber/storage/clickhouse +``` + +### Running the tests + +This module uses [Testcontainers for Go](https://github.com/testcontainers/testcontainers-go/) to run integration tests, which will start a local instance of Clickhouse as a Docker container under the hood. To run the tests, you must have Docker (or another container runtime 100% compatible with the Docker APIs) installed on your machine. + +### Local development + +Before running this implementation, you must ensure a Clickhouse cluster is available. +For local development, we recommend using the Clickhouse Docker image; it contains everything +necessary for the client to operate correctly. + +To start Clickhouse using Docker, issue the following: + +```bash +docker run -d -p 9000:9000 --name some-clickhouse-server --ulimit nofile=262144:262144 clickhouse/clickhouse-server +``` + +After running this command you're ready to start using the storage and connecting to the database. + +### Examples + +You can use the following options to create a clickhouse storage driver: +```go +import "github.com/gofiber/storage/clickhouse" + +// Initialize default config, to connect to localhost:9000 using the memory engine and with a clean table. +store, err := clickhouse.New(clickhouse.Config{ + Host: "localhost", + Port: 9000, + Clean: true, +}) + +// Initialize custom config to connect to a different host/port and use custom engine and with clean table. +store, err := clickhouse.New(clickhouse.Config{ + Host: "some-ip-address", + Port: 9000, + Engine: clickhouse.MergeTree, + Clean: true, +}) + +// Initialize to connect with TLS enabled with your own tls.Config and with clean table. +tlsConfig := config := &tls.Config{...} + +store, err := clickhouse.New(clickhouse.Config{ + Host: "some-ip-address", + Port: 9000, + Clean: true, + TLSConfig: tlsConfig, +}) +``` + +### Config + +```go +// Config defines configuration options for Clickhouse connection. +type Config struct { + // The host of the database. Ex: 127.0.0.1 + Host string + // The port where the database is supposed to listen to. Ex: 9000 + Port int + // The database that the connection should authenticate from + Database string + // The username to be used in the authentication + Username string + // The password to be used in the authentication + Password string + // The name of the table that will store the data + Table string + // The engine that should be used in the table + Engine string + // Should start a clean table, default false + Clean bool + // TLS configuration, default nil + TLSConfig *tls.Config + // Should the connection be in debug mode, default false + Debug bool + // The function to use with the debug config, default print function. It only works when debug is true + Debugf func(format string, v ...any) +} +``` + +### Default Config + +```go +var DefaultConfig = Config{ + Host: "localhost", + Port: 9000, + Engine: "Memory", + Clean: false, +} +``` diff --git a/storage_versioned_docs/version-valkey_v0.x.x/cloudflarekv/README.md b/storage_versioned_docs/version-valkey_v0.x.x/cloudflarekv/README.md new file mode 100644 index 00000000000..619103e762e --- /dev/null +++ b/storage_versioned_docs/version-valkey_v0.x.x/cloudflarekv/README.md @@ -0,0 +1,114 @@ +--- +id: cloudflarekv +title: Cloudflare KV +--- + +![Release](https://img.shields.io/github/v/tag/gofiber/storage?filter=cloudflarekv*) +[![Discord](https://img.shields.io/discord/704680098577514527?style=flat&label=%F0%9F%92%AC%20discord&color=00ACD7)](https://gofiber.io/discord) +![Test](https://img.shields.io/github/actions/workflow/status/gofiber/storage/test-cloudflarekv.yml?label=Tests) +![Security](https://img.shields.io/github/actions/workflow/status/gofiber/storage/gosec.yml?label=Security) +![Linter](https://img.shields.io/github/actions/workflow/status/gofiber/storage/linter.yml?label=Linter) + +A Cloudflare KV storage driver using [cloudflare/cloudflare-go](https://github.com/cloudflare/cloudflare-go). + +**Note: Requires Go 1.21 and above** + +### Table of Contents + +- [Signatures](#signatures) +- [Installation](#installation) +- [Examples](#examples) +- [Config](#config) +- [Default Config](#default-config) + +### Signatures + +```go +func New(config ...Config) Storage +func (s *Storage) Get(key string) ([]byte, error) +func (s *Storage) Set(key string, val []byte, exp time.Duration) error +func (s *Storage) Delete(key string) error +func (s *Storage) Reset() error +func (s *Storage) Close() error +func (s *Storage) Conn() *cloudflare.API +``` + +### Installation + +```bash +go mod init github.com// +``` + +And then install the Cloudflare KV implementation: + +```bash +go get github.com/gofiber/storage/cloudflarekv +``` + +### Examples + +Import the storage package. + +```go +import "github.com/gofiber/storage/cloudflarekv" +``` + +You can use the following methods to create storage. The Key must be an API Token generated with at least `Account.Workers KV Storage` permission. Check the [Create API Token](https://developers.cloudflare.com/fundamentals/api/get-started/create-token/) documentation to generate one. + +```go +// Initialize default config +store := cloudflarekv.New() + +store := cloudflarekv.New(cloudflarekv.Config{ + Key: "", + Email: "", + AccountID: "fiber", + NamespaceID: "fiber", + Reset: false, +}) + +``` + +### Config + +```go +type Config struct { + + // Cloudflare Auth Token + // + // Optional. Default is "" + Key string + + // Cloudflare Email + // + // Optional. Default is "" + Email string + + // Account id + // + // Optional. Default is "fiber" + AccountID string + + // Namespace id + // + // Optional. Default is "fiber" + NamespaceID string + + // Reset clears any existing keys in existing Table + // + // Optional. Default is false + Reset bool +} +``` + +### Default Config + +```go +var ConfigDefault = Config{ + Key: "", + Email: "", + AccountID: "fiber", + NamespaceID: "fiber", + Reset: false, +} +``` diff --git a/storage_versioned_docs/version-valkey_v0.x.x/coherence/README.md b/storage_versioned_docs/version-valkey_v0.x.x/coherence/README.md new file mode 100644 index 00000000000..f4d12aaeb7c --- /dev/null +++ b/storage_versioned_docs/version-valkey_v0.x.x/coherence/README.md @@ -0,0 +1,138 @@ +# Coherence + +A Coherence storage driver using [https://github.com/oracle/coherence-go-client](https://github.com/oracle/coherence-go-client). + +### Table of Contents +- [Signatures](#signatures) +- [Installation](#installation) +- [Examples](#examples) +- [Config](#config) +- [Default Config](#default-config) + +### Signatures +```go +func New(config ...Config) (*Storage, error) +func (s *Storage) Get(key string) ([]byte, error) +func (s *Storage) Set(key string, val []byte, exp time.Duration) error +func (s *Storage) Delete(key string) error +func (s *Storage) Reset() error +func (s *Storage) Close() error +func (s *Storage) Conn() *Session +``` + +### Installation +Coherence is supported on Go versions 1.19 and above: + +Install the coherence implementation: +```bash +go get github.com/gofiber/storage/coherence +``` + +Before running or testing this implementation, you must ensure a Coherence cluster is available. +For local development, we recommend using the Coherence CE Docker image; it contains everything +necessary for the client to operate correctly. + +To start a Coherence cluster using Docker, issue the following: + +```bash +docker run -d -p 1408:1408 ghcr.io/oracle/coherence-ce:22.06.7 +``` + +See the documentation [here](https://pkg.go.dev/github.com/oracle/coherence-go-client/coherence#hdr-Obtaining_a_Session) on connection options +when creating a Coherence session. + +### Examples +Import the storage package. +```go +import "github.com/gofiber/storage/coherence" +``` + +You can use the following possibilities to create a storage: +```go +// Initialize default config, to connect to localhost:1408 using plain text +store, err := coherence.New() + +// Initialize custom config to connect to a different host/port and use plain text and expiry of 5 minutes. +store, err := coherence.New(coherence.Config{ + Address: "my-host:myport", + Expiration: time.Duration(300) * time.Second, // 5 minutes +}) + +// Initialize to connect with TLS enabled with your own tls.Config +tlsConfig := config := &tls.Config{...} + +store, err := coherence.New(coherence.Config{ + Address: "my-host:myport", + TLSConfig: tlsConfig, +}) +``` + +> Note: If you create two stores using `coherence.New()` they will effectivity be identical. +> If you wish to have two separate stores, then you can use: +> ```go +> store1, err := coherence.New(Config{ScopeName: "scope1"}) +> store2, err := coherence.New(Config{ScopeName: "scope2"}) +> ``` + +**Near Caches** + +The latest version of the Coherence Go client introduces near cache support +to cache frequently accessed data in the Go client to avoid sending requests across the network. + +This is particularly useful if you are using sticky sessions via a LBR as this will cache +the session in the Go process and the `Get()` operations will be much quicker. + +When the session is expired on the server it will automatically be removed from the near cache. + +To enable this for you session, you can set the `NearCacheTimeout` to a duration less than the expiry. + +```go +// Initialize default config, to connect to localhost:1408 using plain text +store, err := coherence.New() + +// Use plain text with default expiry of 5 minutes, and a near cache expiry of 2 minutes +store, err := coherence.New(coherence.Config{ + Address: "my-host:myport", + Expiration: time.Duration(300) * time.Second, // 5 minutes + NearCacheTimeout: time.Duration(120) * time.Second, // 2 minutes +}) +``` +> Note: You must ensure your near cache timeout is less that the session timeout. + +### Config + +```go +// Config defines configuration options for Coherence connection. +type Config struct { + // Address to connect to, defaults to "localhost:1408" + Address string + + // Timeout is the default session timeout to connect to Coherence, defaults to 30s + Timeout time.Duration + + // ScopeName defines a scope allowing for multiple storage sessions + ScopeName string + + // Reset indicates if the store should be reset after being created + Reset bool + + // TLSConfig specifies tls.Config to use when connecting, if nil then plain text is used + TLSConfig *tls.Config + + // NearCacheTimeout defines the timeout for a near cache. Is this is set, then a near cache + // with the timeout is created. Note: this must be less than the session timeout or any timeout you specify + // when using Set(). + NearCacheTimeout time.Duration +} +``` + +### Default Config +```go +var DefaultConfig = Config{ + Address: "localhost:1408", + Timeout: time.Duration(120) * time.Seconds, + ScopeName: defaultScopeName, + Reset: false, + NearCacheTimeout: time.Duration(60) * time.Seconds, +} +``` diff --git a/storage_versioned_docs/version-valkey_v0.x.x/couchbase/README.md b/storage_versioned_docs/version-valkey_v0.x.x/couchbase/README.md new file mode 100644 index 00000000000..031f7b9da20 --- /dev/null +++ b/storage_versioned_docs/version-valkey_v0.x.x/couchbase/README.md @@ -0,0 +1,94 @@ +--- +id: couchbase +title: Couchbase +--- + +![Release](https://img.shields.io/github/v/tag/gofiber/storage?filter=couchbase*) +[![Discord](https://img.shields.io/discord/704680098577514527?style=flat&label=%F0%9F%92%AC%20discord&color=00ACD7)](https://gofiber.io/discord) +![Test](https://img.shields.io/github/actions/workflow/status/gofiber/storage/test-couchbase.yml?label=Tests) +![Security](https://img.shields.io/github/actions/workflow/status/gofiber/storage/gosec.yml?label=Security) +![Linter](https://img.shields.io/github/actions/workflow/status/gofiber/storage/linter.yml?label=Linter) + +A Couchbase storage driver using [couchbase/gocb](https://github.com/couchbase/gocb). + +**Note: Requires Go 1.19 and above** + +### Table of Contents +- [Signatures](#signatures) +- [Installation](#installation) +- [Examples](#examples) +- [Config](#config) +- [Default Config](#default-config) + +### Signatures +```go +func New(config ...Config) Storage +func (s *Storage) Get(key string) ([]byte, error) +func (s *Storage) Set(key string, val []byte, exp time.Duration) error +func (s *Storage) Delete(key string) error +func (s *Storage) Reset() error +func (s *Storage) Close() error +func (s *Storage) Conn() *gocb.Cluster +``` +### Installation +Couchbase is tested on the 2 last [Go versions](https://golang.org/dl/) with support for modules. So make sure to initialize one first if you didn't do that yet: +```bash +go mod init github.com// +``` +And then install the Couchbase implementation: +```bash +go get github.com/gofiber/storage/couchbase/v2 +``` + +### Examples +Import the storage package. +```go +import "github.com/gofiber/storage/couchbase/v2" +``` + +You can use the following possibilities to create a storage: +```go +// Initialize default config +store := couchbase.New() + +// Initialize Couchbase storage with custom config +store := couchbase.New(couchbase.Config{ + Host: "127.0.0.1:8091", + Username: "", + Password: "", + Bucket: 0, + ConnectionTimeout: 3* time.Second, + KVTimeout: 1* time.Second, +}) +``` + +### Config +```go +type Config struct { + // The application username to Connect to the Couchbase cluster + Username string + // The application password to Connect to the Couchbase cluster + Password string + // The connection string for the Couchbase cluster + Host string + // The name of the bucket to Connect to + Bucket string + // The timeout for connecting to the Couchbase cluster + ConnectionTimeout time.Duration + // The timeout for performing operations on the Couchbase cluster + KVTimeout time.Duration +} +``` + +### Default Config +```go +// ConfigDefault is the default config +var ConfigDefault = Config{ + Host: "127.0.0.1:8091", + Username: "admin", + Password: "123456", + Bucket: "fiber_storage", + ConnectionTimeout: 3 * time.Second, + KVTimeout: 1 * time.Second, +} +``` diff --git a/storage_versioned_docs/version-valkey_v0.x.x/dynamodb/README.md b/storage_versioned_docs/version-valkey_v0.x.x/dynamodb/README.md new file mode 100644 index 00000000000..1c068c7e466 --- /dev/null +++ b/storage_versioned_docs/version-valkey_v0.x.x/dynamodb/README.md @@ -0,0 +1,143 @@ +--- +id: dynamodb +title: DynamoDB +--- + +![Release](https://img.shields.io/github/v/tag/gofiber/storage?filter=dynamodb*) +[![Discord](https://img.shields.io/discord/704680098577514527?style=flat&label=%F0%9F%92%AC%20discord&color=00ACD7)](https://gofiber.io/discord) +![Test](https://img.shields.io/github/actions/workflow/status/gofiber/storage/test-dynamodb.yml?label=Tests) +![Security](https://img.shields.io/github/actions/workflow/status/gofiber/storage/gosec.yml?label=Security) +![Linter](https://img.shields.io/github/actions/workflow/status/gofiber/storage/linter.yml?label=Linter) + +A DynamoDB storage driver using [aws/aws-sdk-go-v2](https://github.com/aws/aws-sdk-go-v2). + +**Note:** If config fields of credentials not given, credentials are using from the environment variables, ~/.aws/credentials, or EC2 instance role. If config fields of credentials given, credentials are using from config. Look at: [specifying credentials](https://aws.github.io/aws-sdk-go-v2/docs/configuring-sdk/#specifying-credentials) + +**Note: Requires Go 1.19 and above** + +### Table of Contents +- [Signatures](#signatures) +- [Installation](#installation) +- [Examples](#examples) +- [Config](#config) +- [Default Config](#default-config) + + +### Signatures +```go +func New(config Config) Storage + + +func (s *Storage) Get(key string) ([]byte, error) +func (s *Storage) Set(key string, val []byte, exp time.Duration) error +func (s *Storage) Delete(key string) error +func (s *Storage) Reset() error +func (s *Storage) Close() error +func (s *Storage) Conn() *awsdynamodb.Client +``` + +### Installation +DynamoDB is tested on the 2 last [Go versions](https://golang.org/dl/) with support for modules. So make sure to initialize one first if you didn't do that yet: +```bash +go mod init github.com// +``` +And then install the dynamodb implementation: +```bash +go get github.com/gofiber/storage/dynamodb/v2 +``` + +### Examples +Import the storage package. +```go +import "github.com/gofiber/storage/dynamodb/v2" +``` + +You can use the following possibilities to create a storage: +```go +// Initialize dynamodb +store := dynamodb.New(dynamodb.Config{ + +}) +``` + +### Config +```go +type Config struct { + // Region of the DynamoDB service you want to use. + // Valid values: https://docs.aws.amazon.com/general/latest/gr/rande.html#ddb_region. + // E.g. "us-west-2". + // Optional (read from shared config file or environment variable if not set). + // Environment variable: "AWS_REGION". + Region string + + // Name of the DynamoDB table. + // Optional ("fiber_storage" by default). + Table string + + // CustomEndpoint allows you to set a custom DynamoDB service endpoint. + // This is especially useful if you're running a "DynamoDB local" Docker container for local testing. + // Typical value for the Docker container: "http://localhost:8000". + // See https://hub.docker.com/r/amazon/dynamodb-local/. + // Optional ("" by default) + Endpoint string + + // Credentials overrides AWS access key and AWS secret access key. Not recommended. + // + // Optional. Default is Credentials{} + Credentials Credentials + + // The maximum number of times requests that encounter retryable failures should be attempted. + // + // Optional. Default is 3 + MaxAttempts int + + // Reset clears any existing keys in existing Bucket + // + // Optional. Default is false + Reset bool + + // ReadCapacityUnits of the table. + // Only required when the table doesn't exist yet and is created by gokv. + // Optional (5 by default, which is the same default value as when creating a table in the web console) + // 25 RCUs are included in the free tier (across all tables). + // For example calculations, see https://github.com/awsdocs/amazon-dynamodb-developer-guide/blob/c420420a59040c5b3dd44a6e59f7c9e55fc922ef/doc_source/HowItWorks.ProvisionedThroughput. + // For limits, see https://github.com/awsdocs/amazon-dynamodb-developer-guide/blob/c420420a59040c5b3dd44a6e59f7c9e55fc922ef/doc_source/Limits.md#capacity-units-and-provisioned-throughput.md#provisioned-throughput. + ReadCapacityUnits int64 + + // ReadCapacityUnits of the table. + // Only required when the table doesn't exist yet and is created by gokv. + // Optional (5 by default, which is the same default value as when creating a table in the web console) + // 25 RCUs are included in the free tier (across all tables). + // For example calculations, see https://github.com/awsdocs/amazon-dynamodb-developer-guide/blob/c420420a59040c5b3dd44a6e59f7c9e55fc922ef/doc_source/HowItWorks.ProvisionedThroughput. + // For limits, see https://github.com/awsdocs/amazon-dynamodb-developer-guide/blob/c420420a59040c5b3dd44a6e59f7c9e55fc922ef/doc_source/Limits.md#capacity-units-and-provisioned-throughput.md#provisioned-throughput. + WriteCapacityUnits int64 + + // If the table doesn't exist yet, gokv creates it. + // If WaitForTableCreation is true, gokv will block until the table is created, with a timeout of 15 seconds. + // If the table still doesn't exist after 15 seconds, an error is returned. + // If WaitForTableCreation is false, gokv returns the client immediately. + // In the latter case you need to make sure that you don't read from or write to the table before it's created, + // because otherwise you will get ResourceNotFoundException errors. + // Optional (true by default). + WaitForTableCreation *bool +} + +type Credentials struct { + AccessKey string + SecretAccessKey string +} + +``` + +### Default Config +```go +var ConfigDefault = Config{ + Table: "fiber_storage", + Credentials: Credentials{}, + MaxAttempts: 3, + Reset: false, + ReadCapacityUnits: 5, + WriteCapacityUnits: 5, + WaitForTableCreation: aws.Bool(true), +} +``` diff --git a/storage_versioned_docs/version-valkey_v0.x.x/etcd/README.md b/storage_versioned_docs/version-valkey_v0.x.x/etcd/README.md new file mode 100644 index 00000000000..f9f43dabf83 --- /dev/null +++ b/storage_versioned_docs/version-valkey_v0.x.x/etcd/README.md @@ -0,0 +1,87 @@ +--- +id: etcd +title: Etcd +--- + +![Release](https://img.shields.io/github/v/tag/gofiber/storage?filter=etcd*) +[![Discord](https://img.shields.io/discord/704680098577514527?style=flat&label=%F0%9F%92%AC%20discord&color=00ACD7)](https://gofiber.io/discord) +![Test](https://img.shields.io/github/actions/workflow/status/gofiber/storage/test-etcd.yml?label=Tests) +![Security](https://img.shields.io/github/actions/workflow/status/gofiber/storage/gosec.yml?label=Security) +![Linter](https://img.shields.io/github/actions/workflow/status/gofiber/storage/linter.yml?label=Linter) + +A Etcd storage driver using [`etcd-io/etcd`](https://github.com/etcd-io/etcd). + +**Note: Requires Go 1.19 and above** + +### Table of Contents +- [Signatures](#signatures) +- [Installation](#installation) +- [Examples](#examples) +- [Config](#config) +- [Default Config](#default-config) + +### Signatures +```go +func New(config ...Config) *Storage +func (s *Storage) Get(key string) ([]byte, error) +func (s *Storage) Set(key string, val []byte, exp time.Duration) error +func (s *Storage) Delete(key string) error +func (s *Storage) Reset() error +func (s *Storage) Close() error +func (s *Storage) Conn() *clientv3.Client +``` + +### Installation +Etcd is tested on the 2 last [Go versions](https://golang.org/dl/) with support for modules. So make sure to initialize one first if you didn't do that yet: +```bash +go mod init github.com// +``` +And then install the etcd implementation: +```bash +go get github.com/gofiber/storage/etcd/v2 +``` + +### Examples +Import the storage package. +```go +import "github.com/gofiber/storage/etcd/v2" +``` + +You can use the following possibilities to create a storage: +```go +// Initialize default config +store := etcd.New() + +// Initialize custom config +store := etcd.New(Config{ + Endpoints: []string{"localhost:2379"}, +}) + +``` + +### Config +```go +type Config struct { + // Endpoints is a list of URLs. + Endpoints []string + // DialTimeout is the timeout for failing to establish a connection. + DialTimeout time.Duration + // Username is a username for authentication. + Username string + // Password is a password for authentication. + Password string + // TLS holds the client secure credentials, if any. + TLS *tls.Config +} +``` + +### Default Config +```go +var ConfigDefault = Config{ + Endpoints: []string{"localhost:2379"}, + DialTimeout: 2 * time.Second, + Username: "", + Password: "", + TLS: nil, +} +``` diff --git a/storage_versioned_docs/version-valkey_v0.x.x/memcache/README.md b/storage_versioned_docs/version-valkey_v0.x.x/memcache/README.md new file mode 100644 index 00000000000..42ae1451f9a --- /dev/null +++ b/storage_versioned_docs/version-valkey_v0.x.x/memcache/README.md @@ -0,0 +1,82 @@ +--- +id: memcache +title: Memcache +--- + +![Release](https://img.shields.io/github/v/tag/gofiber/storage?filter=memcache*) +[![Discord](https://img.shields.io/discord/704680098577514527?style=flat&label=%F0%9F%92%AC%20discord&color=00ACD7)](https://gofiber.io/discord) +![Test](https://img.shields.io/github/actions/workflow/status/gofiber/storage/test-memcache.yml?label=Tests) +![Security](https://img.shields.io/github/actions/workflow/status/gofiber/storage/gosec.yml?label=Security) +![Linter](https://img.shields.io/github/actions/workflow/status/gofiber/storage/linter.yml?label=Linter) + +A Memcache storage driver using [`bradfitz/gomemcache`](https://github.com/bradfitz/gomemcache). + +**Note: Requires Go 1.19 and above** + +### Table of Contents +- [Signatures](#signatures) +- [Installation](#installation) +- [Examples](#examples) +- [Config](#config) +- [Default Config](#default-config) + +### Signatures +```go +func New(config ...Config) Storage +func (s *Storage) Get(key string) ([]byte, error) +func (s *Storage) Set(key string, val []byte, exp time.Duration) error +func (s *Storage) Delete(key string) error +func (s *Storage) Reset() error +func (s *Storage) Close() error +func (s *Storage) Conn() *mc.Client +``` + +### Installation +Memory is tested on the 2 last [Go versions](https://golang.org/dl/) with support for modules. So make sure to initialize one first if you didn't do that yet: +```bash +go mod init github.com// +``` +And then install the memory implementation: +```bash +go get github.com/gofiber/storage/memory/v2 +``` + +### Examples +Import the storage package. +```go +import "github.com/gofiber/storage/memcache" +``` + +You can use the following possibilities to create a storage: +```go +// Initialize default config +store := memcache.New() + +// Initialize custom config +store := memcache.New(memcache.Config{ + Servers: "localhost:11211", +}) +``` + +### Config +```go +type Config struct { + // Server list divided by , + // i.e. server1:11211, server2:11212 + // + // Optional. Default is "127.0.0.1:11211" + Servers string + + // Reset clears any existing keys in existing Table + // + // Optional. Default is false + Reset bool +} +``` + +### Default Config +```go +var ConfigDefault = Config{ + Servers: "127.0.0.1:11211", +} +``` diff --git a/storage_versioned_docs/version-valkey_v0.x.x/memory/README.md b/storage_versioned_docs/version-valkey_v0.x.x/memory/README.md new file mode 100644 index 00000000000..8cb31506fa1 --- /dev/null +++ b/storage_versioned_docs/version-valkey_v0.x.x/memory/README.md @@ -0,0 +1,79 @@ +--- +id: memory +title: Memory +--- + + +![Release](https://img.shields.io/github/v/tag/gofiber/storage?filter=memory*) +[![Discord](https://img.shields.io/discord/704680098577514527?style=flat&label=%F0%9F%92%AC%20discord&color=00ACD7)](https://gofiber.io/discord) +![Test](https://img.shields.io/github/actions/workflow/status/gofiber/storage/test-memory.yml?label=Tests) +![Security](https://img.shields.io/github/actions/workflow/status/gofiber/storage/gosec.yml?label=Security) +![Linter](https://img.shields.io/github/actions/workflow/status/gofiber/storage/linter.yml?label=Linter) + +An in-memory storage driver. + +**Note: Requires Go 1.19 and above** + +### Table of Contents +- [Signatures](#signatures) +- [Installation](#installation) +- [Examples](#examples) +- [Config](#config) +- [Default Config](#default-config) + + +### Signatures +```go +func New(config ...Config) Storage +func (s *Storage) Get(key string) ([]byte, error) +func (s *Storage) Set(key string, val []byte, exp time.Duration) error +func (s *Storage) Delete(key string) error +func (s *Storage) Reset() error +func (s *Storage) Close() error +func (s *Storage) Conn() map[string]entry +func (s *Storage) Keys() ([][]byte, error) +``` + +### Installation +Memory is tested on the 2 last [Go versions](https://golang.org/dl/) with support for modules. So make sure to initialize one first if you didn't do that yet: +```bash +go mod init github.com// +``` +And then install the memory implementation: +```bash +go get github.com/gofiber/storage/memory/v2 +``` + +### Examples +Import the storage package. +```go +import "github.com/gofiber/storage/memory/v2" +``` + +You can use the following possibilities to create a storage: +```go +// Initialize default config +store := memory.New() + +// Initialize custom config +store := memory.New(memory.Config{ + GCInterval: 10 * time.Second, +}) +``` + +### Config +```go +type Config struct { + // Time before deleting expired keys + // + // Default is 10 * time.Second + GCInterval time.Duration +} +``` + +### Default Config +```go +var ConfigDefault = Config{ + GCInterval: 10 * time.Second, +} +``` diff --git a/storage_versioned_docs/version-valkey_v0.x.x/minio/README.md b/storage_versioned_docs/version-valkey_v0.x.x/minio/README.md new file mode 100644 index 00000000000..9c291f2de25 --- /dev/null +++ b/storage_versioned_docs/version-valkey_v0.x.x/minio/README.md @@ -0,0 +1,142 @@ +--- +id: minio +title: Minio +--- + +![Release](https://img.shields.io/github/v/tag/gofiber/storage?filter=minio*) +[![Discord](https://img.shields.io/discord/704680098577514527?style=flat&label=%F0%9F%92%AC%20discord&color=00ACD7)](https://gofiber.io/discord) +![Test](https://img.shields.io/github/actions/workflow/status/gofiber/storage/test-minio.yml?label=Tests) +![Security](https://img.shields.io/github/actions/workflow/status/gofiber/storage/gosec.yml?label=Security) +![Linter](https://img.shields.io/github/actions/workflow/status/gofiber/storage/linter.yml?label=Linter) + +## Minio + +A Minio storage driver using [minio/minio-go](https://github.com/minio/minio-go). + +**Note: Requires Go 1.19 and above** + +### Table of Contents +- [Signatures](#signatures) +- [Installation](#installation) +- [Examples](#examples) +- [Config](#config) +- [Default Config](#default-config) + +### Signatures +```go +func New(config ...Config) Storage +func (s *Storage) Get(key string) ([]byte, error) +func (s *Storage) Set(key string, val []byte, exp time.Duration) error +func (s *Storage) Delete(key string) error +func (s *Storage) Reset() error +func (s *Storage) Close() error +func (s *Storage) CheckBucket() error +func (s *Storage) CreateBucket() error +func (s *Storage) RemoveBucket() error +func (s *Storage) Conn() *minio.Client +``` +### Installation +Install the Minio implementation: +```bash +go get github.com/gofiber/storage/minio +``` +And then run minio on Docker +```bash +docker run -d --restart always -p 9000:9000 -p 9001:9001 --name storage-minio --volume=minio:/var/lib/minio -e MINIO_ROOT_USER='minio-user' -e MINIO_ROOT_PASSWORD='minio-password' minio/minio server --console-address ":9001" /var/lib/minio +``` + +### Examples +Import the storage package. +```go +import "github.com/gofiber/storage/minio" +``` + +You can use the following possibilities to create a storage: +```go +// Initialize default config +store := minio.New() + +// Initialize custom config +store := minio.New(minio.Config{ + Bucket: "fiber-bucket", + Endpoint: "localhost:9000", + Credentials: Credentials{ + AccessKeyID: "minio-user", + SecretAccessKey: "minio-password", + }, +}) +``` + +### Config +```go +// Config defines the config for storage. +type Config struct { + // Bucket + // Default fiber-bucket + Bucket string + + // Endpoint is a host name or an IP address + Endpoint string + + // Region Set this value to override region cache + // Optional + Region string + + // Token Set this value to provide x-amz-security-token (AWS S3 specific) + // Optional, Default is false + Token string + + // Secure If set to true, https is used instead of http. + // Default is false + Secure bool + + // Reset clears any existing keys in existing Bucket + // Optional. Default is false + Reset bool + + // The maximum number of times requests that encounter retryable failures should be attempted. + // Optional. Default is 10, same as the MinIO client. + MaxRetry int + + // Credentials Minio access key and Minio secret key. + // Need to be defined + Credentials Credentials + + // GetObjectOptions Options for GET requests specifying additional options like encryption, If-Match + GetObjectOptions minio.GetObjectOptions + + // PutObjectOptions + // Allows user to set optional custom metadata, content headers, encryption keys and number of threads for multipart upload operation. + PutObjectOptions minio.PutObjectOptions + + // ListObjectsOptions Options per to list objects + ListObjectsOptions minio.ListObjectsOptions + + // RemoveObjectOptions Allows user to set options + RemoveObjectOptions minio.RemoveObjectOptions +} +``` + +### Default Config +The default configuration lacks Bucket, Region, and Endpoint which are all required and must be overwritten: +```go +// ConfigDefault is the default config +var ConfigDefault = Config{ + Bucket: "fiber-bucket", + Endpoint: "", + Region: "", + Token: "", + Secure: false, + Reset: false, + + Credentials: Credentials{}, + GetObjectOptions: minio.GetObjectOptions{}, + PutObjectOptions: minio.PutObjectOptions{}, + ListObjectsOptions: minio.ListObjectsOptions{}, + RemoveObjectOptions: minio.RemoveObjectOptions{}, +} +type Credentials struct { + AccessKeyID string + SecretAccessKey string +} +``` diff --git a/storage_versioned_docs/version-valkey_v0.x.x/mockstorage/README.md b/storage_versioned_docs/version-valkey_v0.x.x/mockstorage/README.md new file mode 100644 index 00000000000..89c0513c030 --- /dev/null +++ b/storage_versioned_docs/version-valkey_v0.x.x/mockstorage/README.md @@ -0,0 +1,171 @@ +--- +id: mockstorage +title: MockStorage +--- + + +![Release](https://img.shields.io/github/v/tag/gofiber/storage?filter=mockstorage*) +[![Discord](https://img.shields.io/discord/704680098577514527?style=flat&label=%F0%9F%92%AC%20discord&color=00ACD7)](https://gofiber.io/discord) +![Test](https://img.shields.io/github/actions/workflow/status/gofiber/storage/test-mockstorage.yml?label=Tests) +![Security](https://img.shields.io/github/actions/workflow/status/gofiber/storage/gosec.yml?label=Security) +![Linter](https://img.shields.io/github/actions/workflow/status/gofiber/storage/linter.yml?label=Linter) + +A mock storage implementation for Fiber. This storage is not persistent and is only used for testing purposes. + +**Note: Requires Go 1.21 and above** + +## Table of Contents +- [Signatures](#signatures) +- [Installation](#installation) +- [Examples](#examples) +- [Config](#config) +- [Default Config](#default-config) + + +## Signatures + +### Structs + +```go +type Storage struct { + // contains filtered or unexported fields +} + +type Entry struct { + Value []byte + Exp time.Time +} + +type Config struct { + CustomFuncs *CustomFuncs +} + +type CustomFuncs struct { + GetFunc func(key string) ([]byte, error) + SetFunc func(key string, val []byte, exp time.Duration) error + DeleteFunc func(key string) error + ResetFunc func() error + CloseFunc func() error + ConnFunc func() map[string]Entry + KeysFunc func() ([][]byte, error) +} +``` + +### Functions +```go +// New creates a new Storage instance. You can optionally pass a Config. +func New(config ...Config) *Storage + +// Get retrieves the value associated with the given key. +func (s *Storage) Get(key string) ([]byte, error) + +// Set sets the value for the given key, with an optional expiration duration. +func (s *Storage) Set(key string, val []byte, exp time.Duration) error + +// Delete removes the value associated with the given key. +func (s *Storage) Delete(key string) error + +// Reset clears all values from the storage. +func (s *Storage) Reset() error + +// Close performs any necessary cleanup when the storage is no longer needed. +func (s *Storage) Close() error + +// Conn returns a copy of the current state of the storage. +func (s *Storage) Conn() map[string]Entry + +// Keys returns a list of all keys in the storage. +func (s *Storage) Keys() ([][]byte, error) + +// SetCustomFuncs allows you to set custom functions for the storage operations. +func (s *Storage) SetCustomFuncs(custom *CustomFuncs) +``` + +## Installation +MockStorage is tested on the 2 last [Go versions](https://golang.org/dl/) with support for modules. So make sure to initialize one first if you didn't do that yet: +```bash +go mod init github.com// +``` +And then install the mockstorage implementation: +```bash +go get github.com/gofiber/storage/mockstorage +``` + +## Examples +Import the storage package. +```go +import "github.com/gofiber/storage/mockstorage" +``` + +You can use the following possibilities to create a storage: +```go +// Initialize default config +store := mockstorage.New() + +// Set a value in the storage. +err := store.Set("key1", []byte("value1"), 0) +if err != nil { + // handle error +} + +// Get a value from the storage. +val, err := store.Get("key1") +if err != nil { + // handle error +} +fmt.Println(string(val)) // prints "value1" + +// Delete a value from the storage. +err = store.Delete("key1") +if err != nil { + // handle error +} + +// Mocking storage operations in tests: +func TestMyFunction(t *testing.T) { + // Create a new instance of MockStorage + store := mockstorage.New() + + // Mock the Set function + store.SetCustomFuncs(&mockstorage.CustomFuncs{ + Set: func(key string, val []byte, exp time.Duration) error { + if key == "expectedKey" && string(val) == "expectedValue" { + return nil + } + return errors.New("unexpected key or value") + }, + }) + + // Call the function you want to test, which should call store.Set + err := MyFunction(store) + + // Check that the function behaved as expected + if err != nil { + t.Errorf("MyFunction returned an error: %v", err) + } +} +``` + +> **Note:** In the `mockstorage` package, expiration of data is not handled automatically in the background. The data is only marked as expired and removed when you attempt to `Get()` it after its expiration time. If you're using a custom `Get()` function or accessing the data directly using the `Conn()` function, expired data will not be removed. Keep this in mind when writing your tests. + +## Config +```go +type Config struct { + CustomFuncs *CustomFuncs +} +``` + +## Default Config +```go +var ConfigDefault = Config{ + CustomFuncs: &CustomFuncs{ + GetFunc: nil, + SetFunc: nil, + DeleteFunc: nil, + ResetFunc: nil, + CloseFunc: nil, + ConnFunc: nil, + KeysFunc: nil, + }, +} +``` diff --git a/storage_versioned_docs/version-valkey_v0.x.x/mongodb/README.md b/storage_versioned_docs/version-valkey_v0.x.x/mongodb/README.md new file mode 100644 index 00000000000..652edd9e0d9 --- /dev/null +++ b/storage_versioned_docs/version-valkey_v0.x.x/mongodb/README.md @@ -0,0 +1,128 @@ +--- +id: mongodb +title: MongoDB +--- + +![Release](https://img.shields.io/github/v/tag/gofiber/storage?filter=mongodb*) +[![Discord](https://img.shields.io/discord/704680098577514527?style=flat&label=%F0%9F%92%AC%20discord&color=00ACD7)](https://gofiber.io/discord) +![Test](https://img.shields.io/github/actions/workflow/status/gofiber/storage/test-mongodb.yml?label=Tests) +![Security](https://img.shields.io/github/actions/workflow/status/gofiber/storage/gosec.yml?label=Security) +![Linter](https://img.shields.io/github/actions/workflow/status/gofiber/storage/linter.yml?label=Linter) + +A MongoDB storage driver using [mongodb/mongo-go-driver](https://github.com/mongodb/mongo-go-driver). + +**Note: Requires Go 1.19 and above** + +### Table of Contents +- [Signatures](#signatures) +- [Installation](#installation) +- [Examples](#examples) +- [Config](#config) +- [Default Config](#default-config) + +### Signatures +```go +func New(config ...Config) Storage +func (s *Storage) Get(key string) ([]byte, error) +func (s *Storage) Set(key string, val []byte, exp time.Duration) error +func (s *Storage) Delete(key string) error +func (s *Storage) Reset() error +func (s *Storage) Close() error +func (s *Storage) Conn() *mongo.Database +``` +### Installation +MongoDB is tested on the 2 last [Go versions](https://golang.org/dl/) with support for modules. So make sure to initialize one first if you didn't do that yet: +```bash +go mod init github.com// +``` +And then install the mongodb implementation: +```bash +go get github.com/gofiber/storage/mongodb/v2 +``` + +### Examples +Import the storage package. +```go +import "github.com/gofiber/storage/mongodb/v2" +``` + +You can use the following possibilities to create a storage: +```go +// Initialize default config +store := mongodb.New() + +// Initialize custom config +store := mongodb.New(mongodb.Config{ + Host: "127.0.0.1", + Port: 27017, + Database: "fiber", + Collection: "fiber_storage", + Reset: false, +}) + +// Initialize custom config using connection string +store := mongodb.New(mongodb.Config{ + ConnectionURI: "mongodb://user:password@127.0.0.1:27017", + Database: "fiber", + Collection: "fiber_storage", + Reset: false, +}) + +``` + +### Config +```go +type Config struct { + // Connection string to use for DB. Will override all other authentication values if used + // + // Optional. Default is "" + ConnectionURI string + + // Host name where the DB is hosted + // + // Optional. Default is "127.0.0.1" + Host string + + // Port where the DB is listening on + // + // Optional. Default is 27017 + Port int + + // Server username + // + // Optional. Default is "" + Username string + + // Server password + // + // Optional. Default is "" + Password string + + // Database name + // + // Optional. Default is "fiber" + Database string + + // Collection name + // + // Optional. Default is "fiber_storage" + Collection string + + // Reset clears any existing keys in existing Table + // + // Optional. Default is false + Reset bool +} +``` + +### Default Config +```go +var ConfigDefault = Config{ + ConnectionURI: "", + Host: "127.0.0.1", + Port: 27017, + Database: "fiber", + Collection: "fiber_storage", + Reset: false, +} +``` diff --git a/storage_versioned_docs/version-valkey_v0.x.x/mssql/README.md b/storage_versioned_docs/version-valkey_v0.x.x/mssql/README.md new file mode 100644 index 00000000000..fb774fc215a --- /dev/null +++ b/storage_versioned_docs/version-valkey_v0.x.x/mssql/README.md @@ -0,0 +1,146 @@ +--- +id: mssql +title: MSSQL +--- + +![Release](https://img.shields.io/github/v/tag/gofiber/storage?filter=mssql*) +[![Discord](https://img.shields.io/discord/704680098577514527?style=flat&label=%F0%9F%92%AC%20discord&color=00ACD7)](https://gofiber.io/discord) +![Test](https://img.shields.io/github/actions/workflow/status/gofiber/storage/test-mssql.yml?label=Tests) +![Security](https://img.shields.io/github/actions/workflow/status/gofiber/storage/gosec.yml?label=Security) +![Linter](https://img.shields.io/github/actions/workflow/status/gofiber/storage/linter.yml?label=Linter) + +A MSSQL storage driver using [microsoft/go-mssqldb](https://github.com/microsoft/go-mssqldb). + +**Note: Requires Go 1.19 and above** + +### Table of Contents +- [Signatures](#signatures) +- [Installation](#installation) +- [Examples](#examples) +- [Config](#config) +- [Default Config](#default-config) + +### Signatures +```go +func New(config ...Config) Storage +func (s *Storage) Get(key string) ([]byte, error) +func (s *Storage) Set(key string, val []byte, exp time.Duration) error +func (s *Storage) Delete(key string) error +func (s *Storage) Reset() error +func (s *Storage) Close() error +func (s *Storage) Conn() *sql.DB +``` +### Installation +MSSQL is tested on the 2 last [Go versions](https://golang.org/dl/) with support for modules. So make sure to initialize one first if you didn't do that yet: +```bash +go mod init github.com// +``` +And then install the mssql implementation: +```bash +go get github.com/gofiber/storage/mssql/v2 +``` + +### Examples +Import the storage package. +```go +import "github.com/gofiber/storage/mssql/v2" +``` + +You can use the following possibilities to create a storage: +```go +// Initialize default config +store := mssql.New() + +// Initialize custom config +store := mssql.New(mssql.Config{ + Host: "127.0.0.1", + Port: 1433, + Database: "fiber", + Table: "fiber_storage", + Reset: false, + GCInterval: 10 * time.Second, + SslMode: "disable", +}) + +// Initialize custom config using connection string +store := mssql.New(mssql.Config{ + ConnectionURI: "sqlserver://user:password@localhost:1433?database=fiber" + Reset: false, + GCInterval: 10 * time.Second, +}) +``` + +### Config +```go +// Config defines the config for storage. +type Config struct { + // Connection string to use for DB. Will override all other authentication values if used + // + // Optional. Default is "" + ConnectionURI string + + // Host name where the DB is hosted + // + // Optional. Default is "127.0.0.1" + Host string + + // Port where the DB is listening on + // + // Optional. Default is 1433 + Port int + + // Server username + // + // Optional. Default is "" + Username string + + // Server password + // + // Optional. Default is "" + Password string + + // Instance name + // + // Optional. Default is "" + Instance string + + // Database name + // + // Optional. Default is "fiber" + Database string + + // Table name + // + // Optional. Default is "fiber_storage" + Table string + + // Reset clears any existing keys in existing Table + // + // Optional. Default is false + Reset bool + + // Time before deleting expired keys + // + // Optional. Default is 10 * time.Second + GCInterval time.Duration + + // The SSL mode for the connection + // + // Optional. Default is "disable" + SslMode string +} +``` + +### Default Config +```go +var ConfigDefault = Config{ + ConnectionURI: "", + Host: "127.0.0.1", + Port: 1433, + Database: "fiber", + Table: "fiber_storage", + Reset: false, + GCInterval: 10 * time.Second, + SslMode: "disable", +} +``` diff --git a/storage_versioned_docs/version-valkey_v0.x.x/mysql/README.md b/storage_versioned_docs/version-valkey_v0.x.x/mysql/README.md new file mode 100644 index 00000000000..49dafaf3e09 --- /dev/null +++ b/storage_versioned_docs/version-valkey_v0.x.x/mysql/README.md @@ -0,0 +1,146 @@ +--- +id: mysql +title: MySQL +--- + +![Release](https://img.shields.io/github/v/tag/gofiber/storage?filter=mysql*) +[![Discord](https://img.shields.io/discord/704680098577514527?style=flat&label=%F0%9F%92%AC%20discord&color=00ACD7)](https://gofiber.io/discord) +![Test](https://img.shields.io/github/actions/workflow/status/gofiber/storage/test-mysql.yml?label=Tests) +![Security](https://img.shields.io/github/actions/workflow/status/gofiber/storage/gosec.yml?label=Security) +![Linter](https://img.shields.io/github/actions/workflow/status/gofiber/storage/linter.yml?label=Linter) + +A MySQL storage driver using `database/sql` and [go-sql-driver/mysql](https://github.com/go-sql-driver/mysql). + +**Note: Requires Go 1.19 and above** + +### Table of Contents +- [Signatures](#signatures) +- [Installation](#installation) +- [Examples](#examples) +- [Config](#config) +- [Default Config](#default-config) + +### Signatures +```go +func New(config ...Config) Storage +func (s *Storage) Get(key string) ([]byte, error) +func (s *Storage) Set(key string, val []byte, exp time.Duration) error +func (s *Storage) Delete(key string) error +func (s *Storage) Reset() error +func (s *Storage) Close() error +func (s *Storage) Conn() *sql.DB +``` +### Installation +MySQL is tested on the 2 last [Go versions](https://golang.org/dl/) with support for modules. So make sure to initialize one first if you didn't do that yet: +```bash +go mod init github.com// +``` +And then install the mysql implementation: +```bash +go get github.com/gofiber/storage/mysql/v2 +``` + +### Examples +Import the storage package. +```go +import "github.com/gofiber/storage/mysql/v2" +``` + +You can use the following possibilities to create a storage: +```go +// Initialize default config +store := mysql.New() + +// Initialize custom config +store := mysql.New(mysql.Config{ + Host: "127.0.0.1", + Port: 3306, + Database: "fiber", + Table: "fiber_storage", + Reset: false, + GCInterval: 10 * time.Second, +}) + +// Initialize custom config using connection string +store := mysql.New(mysql.Config{ + ConnectionURI: ":@tcp(:)/" + Reset: false, + GCInterval: 10 * time.Second, +}) + +// Initialize custom config using sql db connection +db, _ := sql.Open("mysql", ":@tcp(:)/") +store := mysql.New(mysql.Config{ + Db: db, + Reset: false, + GCInterval: 10 * time.Second, +}) +``` + +### Config +```go +type Config struct { + // DB Will override ConnectionURI and all other authentication values if used + // + // Optional. Default is nil + Db *sql.DB + + // Connection string to use for DB. Will override all other authentication values if used + // + // Optional. Default is "" + ConnectionURI string + + // Host name where the DB is hosted + // + // Optional. Default is "127.0.0.1" + Host string + + // Port where the DB is listening on + // + // Optional. Default is 3306 + Port int + + // Server username + // + // Optional. Default is "" + Username string + + // Server password + // + // Optional. Default is "" + Password string + + // Database name + // + // Optional. Default is "fiber" + Database string + + // Table name + // + // Optional. Default is "fiber_storage" + Table string + + // Reset clears any existing keys in existing Table + // + // Optional. Default is false + Reset bool + + // Time before deleting expired keys + // + // Optional. Default is 10 * time.Second + GCInterval time.Duration +} +``` + +### Default Config +```go +var ConfigDefault = Config{ + ConnectionURI: "", + Host: "127.0.0.1", + Port: 3306, + Database: "fiber", + Table: "fiber_storage", + Reset: false, + GCInterval: 10 * time.Second, +} +``` diff --git a/storage_versioned_docs/version-valkey_v0.x.x/nats/README.md b/storage_versioned_docs/version-valkey_v0.x.x/nats/README.md new file mode 100644 index 00000000000..8e383a383b4 --- /dev/null +++ b/storage_versioned_docs/version-valkey_v0.x.x/nats/README.md @@ -0,0 +1,112 @@ +--- +id: nats +title: Nats +--- + + +![Release](https://img.shields.io/github/v/tag/gofiber/storage?filter=nats*) +[![Discord](https://img.shields.io/discord/704680098577514527?style=flat&label=%F0%9F%92%AC%20discord&color=00ACD7)](https://gofiber.io/discord) +![Test](https://img.shields.io/github/actions/workflow/status/gofiber/storage/test-nats.yml?label=Tests) +![Security](https://img.shields.io/github/actions/workflow/status/gofiber/storage/gosec.yml?label=Security) +![Linter](https://img.shields.io/github/actions/workflow/status/gofiber/storage/linter.yml?label=Linter) + +A NATS Key/Value storage driver. + +## Note: Requires Go 1.20 and above + +### Table of Contents + +- [Signatures](#signatures) +- [Installation](#installation) +- [Examples](#examples) +- [Config](#config) +- [Default Config](#default-config) + +### Signatures + +```go +func New(config ...Config) Storage +func (s *Storage) Get(key string) ([]byte, error) +func (s *Storage) Set(key string, val []byte, exp time.Duration) error +func (s *Storage) Delete(key string) error +func (s *Storage) Reset() error +func (s *Storage) Close() error +func (s *Storage) Conn() (*nats.Conn, jetstream.KeyValue) +func (s *Storage) Keys() ([]string, error) +``` + +### Installation + +[NATS Key/Value Store](https://docs.nats.io/nats-concepts/jetstream/key-value-store) driver is tested on the 2 last [Go versions](https://golang.org/dl/) with support for modules. So make sure to initialize one first if you didn't do that yet: + +```bash +go mod init github.com// +``` + +And then install the nats implementation: + +```bash +go get github.com/gofiber/storage/nats +``` + +### Examples + +Import the storage package. + +```go +import "github.com/gofiber/storage/nats" +``` + +You can use the following options to create a storage driver: + +```go +// Initialize default config +store := nats.New() + +// Initialize custom config +store := nats.New(Config{ + URLs: "nats://127.0.0.1:4443", + NatsOptions: []nats.Option{ + nats.MaxReconnects(2), + // Enable TLS by specifying RootCAs + nats.RootCAs("./testdata/certs/ca.pem"), + }, + KeyValueConfig: jetstream.KeyValueConfig{ + Bucket: "test", + Storage: jetstream.MemoryStorage, + }, +}) +``` + +### Config + +```go +type Config struct { + // Nats URLs, default "nats://127.0.0.1:4222". Can be comma separated list for multiple servers + URLs string + // Nats connection options. See nats_test.go for an example of how to use this. + NatsOptions []nats.Option + // Nats connection name + ClientName string + // Nats context + Context context.Context + // Nats key value config + KeyValueConfig jetstream.KeyValueConfig + // Wait for connection to be established, default: 100ms + WaitForConnection time.Duration +} +``` + +### Default Config + +```go +var ConfigDefault = Config{ + URLs: nats.DefaultURL, + Context: context.Background(), + ClientName: "fiber_storage", + KeyValueConfig: jetstream.KeyValueConfig{ + Bucket: "fiber_storage", + }, + WaitForConnection: 100 * time.Millisecond, +} +``` diff --git a/storage_versioned_docs/version-valkey_v0.x.x/pebble/README.md b/storage_versioned_docs/version-valkey_v0.x.x/pebble/README.md new file mode 100644 index 00000000000..1e811773e65 --- /dev/null +++ b/storage_versioned_docs/version-valkey_v0.x.x/pebble/README.md @@ -0,0 +1,94 @@ +--- +id: pebble +title: Pebble +--- + +![Release](https://img.shields.io/github/v/tag/gofiber/storage?filter=pebble*) +[![Discord](https://img.shields.io/discord/704680098577514527?style=flat&label=%F0%9F%92%AC%20discord&color=00ACD7)](https://gofiber.io/discord) +![Test](https://img.shields.io/github/actions/workflow/status/gofiber/storage/test-pebble.yml?label=Tests) +![Security](https://img.shields.io/github/actions/workflow/status/gofiber/storage/gosec.yml?label=Security) +![Linter](https://img.shields.io/github/actions/workflow/status/gofiber/storage/linter.yml?label=Linter) + +A fast key-value DB using [cockroachdb/pebble](https://github.com/cockroachdb/pebble) + +**Note: Requires Go 1.19 and above** + +### Table of Contents + +- [Signatures](#signatures) +- [Installation](#installation) +- [Examples](#examples) +- [Config](#config) +- [Default Config](#default-config) + +### Signatures + +```go +func New(config ...Config) Storage +func (s *Storage) Get(key string) ([]byte, error) +func (s *Storage) Set(key string, val []byte, exp time.Duration) error +func (s *Storage) Delete(key string) error +func (s *Storage) Reset() error +func (s *Storage) Close() error +func (s *Storage) Conn() *badger.DB +``` + +### Installation + +Pebble is tested on the 2 last [Go versions](https://golang.org/dl/) with support for modules. So make sure to initialize one first if you didn't do that yet: +```bash +go mod init github.com// +``` +Note: This step is only required if you don't have an existing module. + +And then install the Pebble implementation: + +```bash +go get github.com/gofiber/storage/pebble/v2 +``` + +### Examples + +Import the storage package. + +```go +import "github.com/gofiber/storage/pebble/v2" +``` + +You can use the following possibilities to create a storage: + +```go +// Initialize default config +store := pebble.New() + +// Initialize custom config +store := pebble.New(pebble.Config{ + Path: "db", + WriteOptions: &pebble.WriteOptions{}, +}) +``` + +### Config + +```go +type Config struct { + // Database name + // + // Optional. Default is "./db" + Path string + + // Pass write options during write operations + // + // Optional. Default is nil + WriteOptions &pebble.WriteOptions{} +} +``` + +### Default Config + +```go +var ConfigDefault = Config{ + Path: "db", + WriteOptions: &pebble.WriteOptions{}, +} +``` diff --git a/storage_versioned_docs/version-valkey_v0.x.x/postgres/README.md b/storage_versioned_docs/version-valkey_v0.x.x/postgres/README.md new file mode 100644 index 00000000000..23ea62b828d --- /dev/null +++ b/storage_versioned_docs/version-valkey_v0.x.x/postgres/README.md @@ -0,0 +1,137 @@ +--- +id: postgres +title: Postgres +--- + +![Release](https://img.shields.io/github/v/tag/gofiber/storage?filter=postgres*) +[![Discord](https://img.shields.io/discord/704680098577514527?style=flat&label=%F0%9F%92%AC%20discord&color=00ACD7)](https://gofiber.io/discord) +![Test](https://img.shields.io/github/actions/workflow/status/gofiber/storage/test-postgres.yml?label=Tests) +![Security](https://img.shields.io/github/actions/workflow/status/gofiber/storage/gosec.yml?label=Security) +![Linter](https://img.shields.io/github/actions/workflow/status/gofiber/storage/linter.yml?label=Linter) + +A Postgres storage driver using [jackc/pgx](https://github.com/jackc/pgx). + +**Note: Requires Go 1.20 and above** + +### Table of Contents +- [Signatures](#signatures) +- [Installation](#installation) +- [Examples](#examples) +- [Config](#config) +- [Default Config](#default-config) + +### Signatures +```go +func New(config ...Config) Storage +func (s *Storage) Get(key string) ([]byte, error) +func (s *Storage) Set(key string, val []byte, exp time.Duration) error +func (s *Storage) Delete(key string) error +func (s *Storage) Reset() error +func (s *Storage) Close() error +func (s *Storage) Conn() *pgxpool.Pool +``` +### Installation +Postgres is tested on the 2 last [Go versions](https://golang.org/dl/) with support for modules. So make sure to initialize one first if you didn't do that yet: +```bash +go mod init github.com// +``` +And then install the postgres implementation: +```bash +go get github.com/gofiber/storage/postgres/v3 +``` + +### Examples +Import the storage package. +```go +import "github.com/gofiber/storage/postgres/v3" +``` + +You can use the following possibilities to create a storage: +```go +// Initialize default config +store := postgres.New() + +// Initialize custom config +store := postgres.New(postgres.Config{ + DB: dbPool, + Table: "fiber_storage", + Reset: false, + GCInterval: 10 * time.Second, +}) +``` + +### Config +```go +// Config defines the config for storage. +type Config struct { + // DB pgxpool.Pool object will override connection uri and other connection fields + // + // Optional. Default is nil + DB *pgxpool.Pool + + // Connection string to use for DB. Will override all other authentication values if used + // + // Optional. Default is "" + ConnectionURI string + + // Host name where the DB is hosted + // + // Optional. Default is "127.0.0.1" + Host string + + // Port where the DB is listening on + // + // Optional. Default is 5432 + Port int + + // Server username + // + // Optional. Default is "" + Username string + + // Server password + // + // Optional. Default is "" + Password string + + // Database name + // + // Optional. Default is "fiber" + Database string + + // Table name + // + // Optional. Default is "fiber_storage" + Table string + + // The SSL mode for the connection + // + // Optional. Default is "disable" + SSLMode string + + // Reset clears any existing keys in existing Table + // + // Optional. Default is false + Reset bool + + // Time before deleting expired keys + // + // Optional. Default is 10 * time.Second + GCInterval time.Duration +} +``` + +### Default Config +```go +// ConfigDefault is the default config +var ConfigDefault = Config{ + ConnectionURI: "", + Host: "127.0.0.1", + Port: 5432, + Database: "fiber", + Table: "fiber_storage", + SSLMode: "disable", + Reset: false, + GCInterval: 10 * time.Second, +} +``` diff --git a/storage_versioned_docs/version-valkey_v0.x.x/redis/README.md b/storage_versioned_docs/version-valkey_v0.x.x/redis/README.md new file mode 100644 index 00000000000..aae925bc18c --- /dev/null +++ b/storage_versioned_docs/version-valkey_v0.x.x/redis/README.md @@ -0,0 +1,196 @@ +--- +id: redis +title: Redis +--- + +![Release](https://img.shields.io/github/v/tag/gofiber/storage?filter=redis*) +[![Discord](https://img.shields.io/discord/704680098577514527?style=flat&label=%F0%9F%92%AC%20discord&color=00ACD7)](https://gofiber.io/discord) +![Test](https://img.shields.io/github/actions/workflow/status/gofiber/storage/test-redis.yml?label=Tests) +![Security](https://img.shields.io/github/actions/workflow/status/gofiber/storage/gosec.yml?label=Security) +![Linter](https://img.shields.io/github/actions/workflow/status/gofiber/storage/linter.yml?label=Linter) + +A Redis storage driver using [go-redis/redis](https://github.com/go-redis/redis). + +**Note: Requires Go 1.19 and above** + +### Table of Contents +- [Signatures](#signatures) +- [Installation](#installation) +- [Examples](#examples) +- [Config](#config) +- [Default Config](#default-config) + +### Signatures +```go +func New(config ...Config) Storage +func (s *Storage) Get(key string) ([]byte, error) +func (s *Storage) Set(key string, val []byte, exp time.Duration) error +func (s *Storage) Delete(key string) error +func (s *Storage) Reset() error +func (s *Storage) Close() error +func (s *Storage) Conn() redis.UniversalClient +func (s *Storage) Keys() ([][]byte, error) +``` +### Installation +Redis is tested on the 2 last [Go versions](https://golang.org/dl/) with support for modules. So make sure to initialize one first if you didn't do that yet: +```bash +go mod init github.com// +``` +And then install the redis implementation: +```bash +go get github.com/gofiber/storage/redis/v3 +``` + +### Examples +Import the storage package. +```go +import "github.com/gofiber/storage/redis/v3" +``` + +You can use the one of the following options to create a Redis Storage: +```go +// Initialize default config +store := redis.New() + +// Initialize custom config +store := redis.New(redis.Config{ + Host: "127.0.0.1", + Port: 6379, + Username: "", + Password: "", + Database: 0, + Reset: false, + TLSConfig: nil, + PoolSize: 10 * runtime.GOMAXPROCS(0), +}) + +// Initialize Redis Failover Client +store := redis.New(redis.Config{ + MasterName: "master-name", + Addrs: []string{":6379"}, +}) + +// Initialize Redis Cluster Client +store := redis.New(redis.Config{ + Addrs: []string{":6379", ":6380"}, +}) + +// Create a client with support for TLS +cer, err := tls.LoadX509KeyPair("./client.crt", "./client.key") +if err != nil { + log.Println(err) + return +} +tlsCfg := &tls.Config{ + MinVersion: tls.VersionTLS12, + InsecureSkipVerify: true, + Certificates: []tls.Certificate{cer}, +} +store = redis.New(redis.Config{ + URL: "redis://:@127.0.0.1:6379/", + TLSConfig: tlsCfg, + Reset: false, +}) + +// Create a client with a Redis URL with all information. +store = redis.New(redis.Config{ + URL: "redis://:@127.0.0.1:6379/", + Reset: false, +}) +``` + +### Config +```go +type Config struct { + // Host name where the DB is hosted + // + // Optional. Default is "127.0.0.1" + Host string + + // Port where the DB is listening on + // + // Optional. Default is 6379 + Port int + + // Server username + // + // Optional. Default is "" + Username string + + // Server password + // + // Optional. Default is "" + Password string + + // Database to be selected after connecting to the server. + // + // Optional. Default is 0 + Database int + + // URL standard format Redis URL. If this is set all other config options, Host, Port, Username, Password, Database have no effect. + // + // Example: redis://:@localhost:6379/ + // Optional. Default is "" + URL string + + // Either a single address or a seed list of host:port addresses, this enables FailoverClient and ClusterClient + // + // Optional. Default is []string{} + Addrs []string + + // MasterName is the sentinel master's name + // + // Optional. Default is "" + MasterName string + + // ClientName will execute the `CLIENT SETNAME ClientName` command for each conn. + // + // Optional. Default is "" + ClientName string + + // SentinelUsername + // + // Optional. Default is "" + SentinelUsername string + + // SentinelPassword + // + // Optional. Default is "" + SentinelPassword string + + // Reset clears any existing keys in existing Collection + // + // Optional. Default is false + Reset bool + + // TLS Config to use. When set TLS will be negotiated. + // + // Optional. Default is nil + TLSConfig *tls.Config + + // Maximum number of socket connections. + // + // Optional. Default is 10 connections per every available CPU as reported by runtime.GOMAXPROCS. + PoolSize int +} +``` + +### Default Config +```go +var ConfigDefault = Config{ + Host: "127.0.0.1", + Port: 6379, + Username: "", + Password: "", + URL: "", + Database: 0, + Reset: false, + TLSConfig: nil, + PoolSize: 10 * runtime.GOMAXPROCS(0), + Addrs: []string{}, + MasterName: "", + ClientName: "", + SentinelUsername: "", + SentinelPassword: "", +} +``` diff --git a/storage_versioned_docs/version-valkey_v0.x.x/ristretto/README.md b/storage_versioned_docs/version-valkey_v0.x.x/ristretto/README.md new file mode 100644 index 00000000000..f7b3e8a7656 --- /dev/null +++ b/storage_versioned_docs/version-valkey_v0.x.x/ristretto/README.md @@ -0,0 +1,86 @@ +--- +id: ristretto +title: Ristretto +--- + +![Release](https://img.shields.io/github/v/tag/gofiber/storage?filter=ristretto*) +[![Discord](https://img.shields.io/discord/704680098577514527?style=flat&label=%F0%9F%92%AC%20discord&color=00ACD7)](https://gofiber.io/discord) +![Test](https://img.shields.io/github/actions/workflow/status/gofiber/storage/test-ristretto.yml?label=Tests) +![Security](https://img.shields.io/github/actions/workflow/status/gofiber/storage/gosec.yml?label=Security) +![Linter](https://img.shields.io/github/actions/workflow/status/gofiber/storage/linter.yml?label=Linter) + +A Memory-bound storage driver using [`dgraph-io/ristretto`](https://github.com/dgraph-io/ristretto). + +**Note: Requires Go 1.19 and above** + +### Table of Contents +- [Signatures](#signatures) +- [Installation](#installation) +- [Examples](#examples) +- [Config](#config) +- [Default Config](#default-config) + + +### Signatures +```go +func New(config ...Config) Storage +func (s *Storage) Get(key string) ([]byte, error) +func (s *Storage) Set(key string, val []byte, exp time.Duration) error +func (s *Storage) Delete(key string) error +func (s *Storage) Reset() error +func (s *Storage) Close() error +func (s *Storage) Conn() *ristretto.Cache +``` + +### Installation +Ristretto is tested on the 2 last [Go versions](https://golang.org/dl/) with support for modules. So make sure to initialize one first if you didn't do that yet: +```bash +go mod init github.com// +``` +And then install the ristretto implementation: +```bash +go get github.com/gofiber/storage/ristretto/v2 +``` + +### Examples +Import the storage package. +```go +import "github.com/gofiber/storage/ristretto/v2" +``` + +You can use the following possibilities to create a storage: +```go +// Initialize default config +store := ristretto.New() + +// Initialize custom config +store := ristretto.New(ristretto.Config{ + NumCounters: 1e7, // number of keys to track frequency of (10M). + MaxCost: 1 << 30, // maximum cost of cache (1GB). + BufferItems: 64, // number of keys per Get buffer. +}) +``` + +### Config +```go +type Config struct { + // NumCounters number of keys to track frequency of (10M). + NumCounters int64 + + // MaxCost maximum cost of cache (1GB). + MaxCost int64 + + // BufferItems number of keys per Get buffer. + BufferItems int64 +} +``` + +### Default Config +```go +var ConfigDefault = Config{ + NumCounters: 1e7, + MaxCost: 1 << 30, + BufferItems: 64, + DefaultCost: 1, +} +``` diff --git a/storage_versioned_docs/version-valkey_v0.x.x/rueidis/README.md b/storage_versioned_docs/version-valkey_v0.x.x/rueidis/README.md new file mode 100644 index 00000000000..5646063b863 --- /dev/null +++ b/storage_versioned_docs/version-valkey_v0.x.x/rueidis/README.md @@ -0,0 +1,212 @@ +--- +id: rueidis +title: Rueidis +--- + +![Release](https://img.shields.io/github/v/tag/gofiber/storage?filter=rueidis*) +[![Discord](https://img.shields.io/discord/704680098577514527?style=flat&label=%F0%9F%92%AC%20discord&color=00ACD7)](https://gofiber.io/discord) +![Test](https://img.shields.io/github/actions/workflow/status/gofiber/storage/test-rueidis.yml?label=Tests) +![Security](https://img.shields.io/github/actions/workflow/status/gofiber/storage/gosec.yml?label=Security) +![Linter](https://img.shields.io/github/actions/workflow/status/gofiber/storage/linter.yml?label=Linter) + +A fast Redis Storage that does auto pipelining and supports client side caching. [redis/rueidis](https://github.com/redis/rueidis). + +**Note: Requires Go 1.20 and above** + +### Table of Contents +- [Signatures](#signatures) +- [Installation](#installation) +- [Examples](#examples) +- [Config](#config) +- [Default Config](#default-config) + +### Signatures +```go +func New(config ...Config) Storage +func (s *Storage) Get(key string) ([]byte, error) +func (s *Storage) Set(key string, val []byte, exp time.Duration) error +func (s *Storage) Delete(key string) error +func (s *Storage) Reset() error +func (s *Storage) Close() error +func (s *Storage) Conn() rueidis.Client +``` +### Installation +Rueidis is tested on the latest [Go version](https://golang.org/dl/) with support for modules. So make sure to initialize one first if you didn't do that yet: +```bash +go mod init github.com// +``` +And then install the rueidis implementation: +```bash +go get github.com/gofiber/storage/rueidis +``` + +### Examples +Import the storage package. +```go +import "github.com/gofiber/storage/rueidis" +``` + +You can use the one of the following options to create a Rueidis Storage: +```go +// Initialize default config (localhost:6379) +store := rueidis.New() + +// Initialize custom config +store := rueidis.New(rueidis.Config{ + InitAddress: []string{"localhost:6380"}, + Username: "", + Password: "", + Database: 0, + Reset: false, + TLSConfig: nil, +}) + +// Initialize using Rueidis URL +store := rueidis.New(rueidis.Config{ + URL: "redis://localhost:6379", +}) + +// Initialize Rueidis Cluster Client +store := rueidis.New(rueidis.Config{ + InitAddress: []string{":6379", ":6380"}, +}) + +// Create a client with support for TLS +cer, err := tls.LoadX509KeyPair("./client.crt", "./client.key") +if err != nil { + log.Println(err) + return +} +tlsCfg := &tls.Config{ + MinVersion: tls.VersionTLS12, + InsecureSkipVerify: true, + Certificates: []tls.Certificate{cer}, +} +store = rueidis.New(rueidis.Config{ + InitAddress: []string{"localhost:6380"}, + Username: "", + Password: "", + SelectDB: 0, + TLSConfig: tlsCfg, +}) + +``` + +### Config +```go +type Config struct { + // Server username + // + // Optional. Default is "" + Username string + + // Server password + // + // Optional. Default is "" + Password string + + // ClientName will execute the `CLIENT SETNAME ClientName` command for each conn. + // + // Optional. Default is "" + ClientName string + + // URL standard format Redis URL. If this is set all other config options, InitAddress, Username, Password, ClientName, and SelectDB have no effect. + // + // Example: redis://:@localhost:6379/ + // Optional. Default is "" + URL string + + // SelectDB to be selected after connecting to the server. + // + // Optional. Default is 0 + SelectDB int + + // Either a single address or a seed list of host:port addresses, this enables FailoverClient and ClusterClient + // + // Optional. Default is []string{"127.0.0.1:6379"} + InitAddress []string + + // TLS Config to use. When set TLS will be negotiated. + // + // Optional. Default is nil + TLSConfig *tls.Config + + // CacheSizeEachConn is redis client side cache size that bind to each TCP connection to a single redis instance. + // + // Optional. The default is DefaultCacheBytes: 128 * (1 << 20) + CacheSizeEachConn int + + // RingScaleEachConn sets the size of the ring buffer in each connection to (2 ^ RingScaleEachConn). + // + // Optional. The default is RingScaleEachConn, which results into having a ring of size 2^10 for each connection. + RingScaleEachConn int + + // ReadBufferEachConn is the size of the bufio.NewReaderSize for each connection, default to DefaultReadBuffer (0.5 MiB). + // + // Optional. The default is DefaultReadBuffer: 1 << 19 + ReadBufferEachConn int + + // WriteBufferEachConn is the size of the bufio.NewWriterSize for each connection, default to DefaultWriteBuffer (0.5 MiB). + // + // Optional. The default is DefaultWriteBuffer: 1 << 19 + WriteBufferEachConn int + + // BlockingPoolSize is the size of the connection pool shared by blocking commands (ex BLPOP, XREAD with BLOCK). + // + // Optional. The default is DefaultPoolSize: 1000 + BlockingPoolSize int + + // PipelineMultiplex determines how many tcp connections used to pipeline commands to one redis instance. + // + // Optional. The default for single and sentinel clients is 2, which means 4 connections (2^2). + PipelineMultiplex int + + // DisableRetry disables retrying read-only commands under network errors + // + // Optional. The default is False + DisableRetry bool + + // DisableCache falls back Client.DoCache/Client.DoMultiCache to Client.Do/Client.DoMulti + // + // Optional. The default is false + DisableCache bool + + // AlwaysPipelining makes rueidis.Client always pipeline redis commands even if they are not issued concurrently. + // + // Optional. The default is true + AlwaysPipelining bool + + // Reset clears any existing keys in existing Collection + // + // Optional. Default is false + Reset bool + + // CacheTTL TTL + // + // Optional. Default is time.Minute + CacheTTL time.Duration +} +``` + +### Default Config +```go +var ConfigDefault = Config{ + Username: "", + Password: "", + ClientName: "", + SelectDB: 0, + InitAddress: []string{"127.0.0.1:6379"}, + TLSConfig: nil, + CacheSizeEachConn: rueidis.DefaultCacheBytes, + RingScaleEachConn: rueidis.DefaultRingScale, + ReadBufferEachConn: rueidis.DefaultReadBuffer, + WriteBufferEachConn: rueidis.DefaultWriteBuffer, + BlockingPoolSize: rueidis.DefaultPoolSize, + PipelineMultiplex: 2, + DisableRetry: false, + DisableCache: false, + AlwaysPipelining: true, + Reset: false, + CacheTTL: time.Minute, +} +``` diff --git a/storage_versioned_docs/version-valkey_v0.x.x/s3/README.md b/storage_versioned_docs/version-valkey_v0.x.x/s3/README.md new file mode 100644 index 00000000000..15890a195e4 --- /dev/null +++ b/storage_versioned_docs/version-valkey_v0.x.x/s3/README.md @@ -0,0 +1,163 @@ +--- +id: s3 +title: S3 +--- + +![Release](https://img.shields.io/github/v/tag/gofiber/storage?filter=s3*) +[![Discord](https://img.shields.io/discord/704680098577514527?style=flat&label=%F0%9F%92%AC%20discord&color=00ACD7)](https://gofiber.io/discord) +![Test](https://img.shields.io/github/actions/workflow/status/gofiber/storage/test-s3.yml?label=Tests) +![Security](https://img.shields.io/github/actions/workflow/status/gofiber/storage/gosec.yml?label=Security) +![Linter](https://img.shields.io/github/actions/workflow/status/gofiber/storage/linter.yml?label=Linter) + +A S3 storage driver using [aws/aws-sdk-go-v2](https://github.com/aws/aws-sdk-go-v2). + +**Note:** If config fields of credentials not given, credentials are using from the environment variables, ~/.aws/credentials, or EC2 instance role. If config fields of credentials given, credentials are using from config. Look at: [specifying credentials](https://aws.github.io/aws-sdk-go-v2/docs/configuring-sdk/#specifying-credentials) + +**Note: Requires Go 1.19 and above** + +### Table of Contents +- [Signatures](#signatures) +- [Installation](#installation) +- [Examples](#examples) +- [Config](#config) +- [Default Config](#default-config) + +### Signatures +```go +func New(config ...Config) Storage +func (s *Storage) Get(key string) ([]byte, error) +func (s *Storage) Set(key string, val []byte, exp time.Duration) error +func (s *Storage) Delete(key string) error +func (s *Storage) Reset() error +func (s *Storage) Close() error +func (s *Storage) Conn() *s3.Client + +// Additional useful methods. +func (s *Storage) CreateBucket(bucket string) error +func (s *Storage) DeleteBucket(bucket string) error +func (s *Storage) DeleteMany(keys ...string) error +func (s *Storage) SetWithChecksum(key string, val []byte, checksum map[types.ChecksumAlgorithm][]byte) error +``` + +### Installation + +S3 is tested on the 2 last [Go versions](https://golang.org/dl/) with support for modules. So make sure to initialize one first if you didn't do that yet: +```bash +go mod init github.com// +``` +And then install the s3 implementation: +```bash +go get github.com/gofiber/storage/s3/v2 +``` + +### Examples + +Import the storage package. + +```go +import "github.com/gofiber/storage/s3/v2" +``` + +You can use the following possibilities to create a storage: +```go +// Initialize default config +store := s3.New() + +// Initialize custom config +store := s3.New(s3.Config{ + Bucket: "my-bucket-url", + Endpoint: "my-endpoint", + Region: "my-region", + Reset: false, +}) +``` + +Create an object with `Set()`: +```go +err := store.Set("my-key", []byte("my-value")) +``` + +Or, call `SetWithChecksum()` to create an object with checksum to +ask S3 server to verify data integrity on server side: + +> Currently 4 algorithms are supported: +> - types.ChecksumAlgorithmCrc32 (`CRC32`) +> - types.ChecksumAlgorithmCrc32c (`CRC32C`) +> - types.ChecksumAlgorithmSha1 (`SHA1`) +> - types.ChecksumAlgorithmSha256 (`SHA256`) +> +> For more information, see [PutObjectInput](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/service/s3#PutObjectInput). + +```go +key := "my-key" +val := []byte("my-value") + +hash := sha256.New() +hash.Write(val) +sha256sum := hash.Sum(nil) + +// import "github.com/aws/aws-sdk-go-v2/service/s3/types" +checksum = map[types.ChecksumAlgorithm][]byte{ + types.ChecksumAlgorithmSha256: sha256sum, +} + +err := store.SetWithChecksum(key, val, checksum) +``` + +### Config +```go +// Config defines the config for storage. +type Config struct { + // S3 bucket name + Bucket string + + // AWS endpoint + Endpoint string + + // AWS region + Region string + + // Request timeout + // + // Optional. Default is 0 (no timeout) + RequestTimeout time.Duration + + // Reset clears any existing keys in existing Bucket + // + // Optional. Default is false + Reset bool + + // Credentials overrides AWS access key and AWS secret access key. Not recommended. + // + // Optional. Default is Credentials{} + Credentials Credentials + + // The maximum number of times requests that encounter retryable failures should be attempted. + // + // Optional. Default is 3 + MaxAttempts int + +} + +type Credentials struct { + AccessKey string + SecretAccessKey string +} +``` + +### Default Config + +The default configuration lacks Bucket, Region, and Endpoint which are all required and must be overwritten: + +```go +// ConfigDefault is the default config +var ConfigDefault = Config{ + Bucket: "", + Region: "", + Endpoint: "", + Credentials: Credentials{}, + MaxAttempts: 3, + RequestTimeout: 0, + Reset: false, +} +``` diff --git a/storage_versioned_docs/version-valkey_v0.x.x/scylladb/README.md b/storage_versioned_docs/version-valkey_v0.x.x/scylladb/README.md new file mode 100644 index 00000000000..fabe2882b72 --- /dev/null +++ b/storage_versioned_docs/version-valkey_v0.x.x/scylladb/README.md @@ -0,0 +1,183 @@ +--- +id: scylladb +title: ScyllaDb +--- + +![Release](https://img.shields.io/github/v/tag/gofiber/storage?filter=scylladb*) +[![Discord](https://img.shields.io/discord/704680098577514527?style=flat&label=%F0%9F%92%AC%20discord&color=00ACD7)](https://gofiber.io/discord) +![Test](https://img.shields.io/github/actions/workflow/status/gofiber/storage/test-scylladb.yml?label=Tests) +![Security](https://img.shields.io/github/actions/workflow/status/gofiber/storage/gosec.yml?label=Security) +![Linter](https://img.shields.io/github/actions/workflow/status/gofiber/storage/linter.yml?label=Linter) + +# ScyllaDb + +A ScyllaDb storage engine for [Fiber](https://github.com/gofiber/fiber) using [gocql](https://github.com/scylladb/gocql). + +### Table of Contents +- [Signatures](#signatures) +- [Installation](#installation) +- [Examples](#examples) +- [Config](#config) +- [Default Config](#default-config) + +### Signatures +```go +func New(config ...Config) Storage +func (s *Storage) Get(key string) ([]byte, error) +func (s *Storage) Set(key string, value []byte, expire time.Duration) error +func (s *Storage) Delete(key string) error +func (s *Storage) Reset() error +func (s *Storage) Close() error +func (s *Storage) Conn() *gocql.Session +``` + +### Installation +ScyllaDb is tested on the 2 last [Go versions](https://golang.org/dl/) with support for modules. So make sure to initialize one first if you didn't do that yet: +```bash +go mod init github.com// +``` +And then install the scylladb implementation: +```bash +go get github.com/gofiber/storage/scylladb +``` + +### Examples +Import the storage package. +```go +import "github.com/gofiber/storage/scylladb" +``` + +You can use the following possibilities to create a storage: +```go +// Initialize default config +store := scylladb.New() + +// Initialize custom config +store := scylladb.New(scylladb.Config{ + Keyspace: "fiber", + Hosts: []string{"127.0.0.1"}, + Port: 9042, + Table: "fiber_storage", + Consistency: "ONE", + Reset: false, +}) + +// Initialize with support for TLS (SslOptions configures TLS use) +// +// InsecureSkipVerify and EnableHostVerification interact as follows: +// +// |Config.InsecureSkipVerify | EnableHostVerification | Result | +// |--------------------------|------------------------|--------------------| +// |Config is nil | false | do not verify host | +// |Config is nil | true | verify host | +// |false | false | verify host | +// |true | false | do not verify host | +// |false | true | verify host | +// |true | true | verify host | +store := New( + Config{ + Keyspace: "fiber", + Hosts: []string{"127.0.0.1"}, + Port: 9042, + Table: "fiber_storage", + Consistency: "ONE", + SslOpts: &gocql.SslOptions{ + Config: &tls.Config{ + InsecureSkipVerify: false, // Set this too false to enable certificate verification + }, + CertPath: "/path/to/client_cert.pem", // Path to the client certificate + KeyPath: "/path/to/client_key.pem", // Path to the client certificate's private key + CaPath: "/path/to/ca_cert.pem", // Path to the CA certificate + EnableHostVerification: true, // Enable hostname verification + }, + Reset: false, + }, +) + +// Initialize custom config using scylladb connection +cluster, _ := gocql.NewCluster("127.0.0.1") +cluster.Keyspace = "fiber" +cluster.Port = 9042 + +session, _ := cluster.CreateSession() +store := scylladb.New(scylladb.Config{ + Session: session, + Keyspace: "fiber", + Table: "fiber_storage", + Reset: false, +}) +``` + +### Config +```go +type Config struct { + // Session is provided by the user to use an existing ScyllaDb session + // Session Will override Keyspace and all other authentication values if used + // + // Optional. Default is nil + Session *gocql.Session + + // Keyspace name + // + // Optional. Default is "fiber" + Keyspace string + + // Hosts are an array of network addresses for establishing initial connections + // You have the flexibility to specify one or multiple addresses as needed + // + // Optional. Default is "127.0.0.1" + Hosts []string + + // Port where the ScyllaDb cluster is listening on + // + // Optional. Default is 9042 + Port int + + // Username for ScyllaDb cluster + // + // Optional. Default is "" + Username string + + // Password for ScyllaDb cluster + // + // Optional. Default is "" + Password string + + // Table name + // + // Optional. Default is "fiber_storage" + Table string + + // Level of the consistency + // + // Optional. Default is "LOCAL_ONE" + Consistency string + + // SslOpts configures TLS use. + // + // Optional. Default is nil + SslOpts *gocql.SslOptions + + // Reset clears any existing keys in existing Table + // + // Optional. Default is false + Reset bool +} +``` + +### Default Config +```go +// ConfigDefault is the default config +var ConfigDefault = Config{ + Session: nil, + Keyspace: "fiber", + Hosts: []string{"127.0.0.1"}, + Username: "", + Password: "", + Port: 9042, + Table: "fiber_storage", + Consistency: "LOCAL_ONE", + SslOpts: nil, + Reset: false, +} +``` diff --git a/storage_versioned_docs/version-valkey_v0.x.x/sqlite3/README.md b/storage_versioned_docs/version-valkey_v0.x.x/sqlite3/README.md new file mode 100644 index 00000000000..9508db9b423 --- /dev/null +++ b/storage_versioned_docs/version-valkey_v0.x.x/sqlite3/README.md @@ -0,0 +1,121 @@ +--- +id: sqlite3 +title: SQLite3 +--- + +![Release](https://img.shields.io/github/v/tag/gofiber/storage?filter=sqlite3*) +[![Discord](https://img.shields.io/discord/704680098577514527?style=flat&label=%F0%9F%92%AC%20discord&color=00ACD7)](https://gofiber.io/discord) +![Test](https://img.shields.io/github/actions/workflow/status/gofiber/storage/test-sqlite3.yml?label=Tests) +![Security](https://img.shields.io/github/actions/workflow/status/gofiber/storage/gosec.yml?label=Security) +![Linter](https://img.shields.io/github/actions/workflow/status/gofiber/storage/linter.yml?label=Linter) + +A SQLite3 storage driver using [mattn/go-sqlite3](https://github.com/mattn/go-sqlite3). + +**Note: Requires Go 1.19 and above** + +### Table of Contents +- [Signatures](#signatures) +- [Installation](#installation) +- [Examples](#examples) +- [Config](#config) +- [Default Config](#default-config) + +### Signatures +```go +func New(config ...Config) Storage +func (s *Storage) Get(key string) ([]byte, error) +func (s *Storage) Set(key string, val []byte, exp time.Duration) error +func (s *Storage) Delete(key string) error +func (s *Storage) Reset() error +func (s *Storage) Close() error +func (s *Storage) Conn() *sql.DB +``` +### Installation +SQLite3 is tested on the 2 last [Go versions](https://golang.org/dl/) with support for modules. So make sure to initialize one first if you didn't do that yet: +```bash +go mod init github.com// +``` +And then install the sqlite3 implementation: +```bash +go get github.com/gofiber/storage/sqlite3/v2 +``` + +### Examples +Import the storage package. +```go +import "github.com/gofiber/storage/sqlite3/v2" +``` + +You can use the following possibilities to create a storage: +```go +// Initialize default config +store := sqlite3.New() + +// Initialize custom config +store := sqlite3.New(sqlite3.Config{ + Database: "./fiber.sqlite3", + Table: "fiber_storage", + Reset: false, + GCInterval: 10 * time.Second, + MaxOpenConns: 100, + MaxIdleConns: 100, + ConnMaxLifetime: 1 * time.Second, +}) +``` + +### Config +```go +type Config struct { + // Database name + // + // Optional. Default is "fiber" + Database string + + // Table name + // + // Optional. Default is "fiber_storage" + Table string + + // Reset clears any existing keys in existing Table + // + // Optional. Default is false + Reset bool + + // Time before deleting expired keys + // + // Optional. Default is 10 * time.Second + GCInterval time.Duration + + // ////////////////////////////////// + // Adaptor related config options // + // ////////////////////////////////// + + // MaxIdleConns sets the maximum number of connections in the idle connection pool. + // + // Optional. Default is 100. + MaxIdleConns int + + // MaxOpenConns sets the maximum number of open connections to the database. + // + // Optional. Default is 100. + MaxOpenConns int + + // ConnMaxLifetime sets the maximum amount of time a connection may be reused. + // + // Optional. Default is 1 second. + ConnMaxLifetime time.Duration +} +``` + +### Default Config +```go +var ConfigDefault = Config{ + Database: "./fiber.sqlite3", + Table: "fiber_storage", + Reset: false, + GCInterval: 10 * time.Second, + MaxOpenConns: 100, + MaxIdleConns: 100, + ConnMaxLifetime: 1 * time.Second, +} +``` diff --git a/storage_versioned_docs/version-valkey_v0.x.x/valkey/README.md b/storage_versioned_docs/version-valkey_v0.x.x/valkey/README.md new file mode 100644 index 00000000000..c87e2781081 --- /dev/null +++ b/storage_versioned_docs/version-valkey_v0.x.x/valkey/README.md @@ -0,0 +1,222 @@ +--- +id: valkey +title: Valkey +--- + +![Release](https://img.shields.io/github/v/tag/gofiber/storage?filter=valkey*) +[![Discord](https://img.shields.io/discord/704680098577514527?style=flat&label=%F0%9F%92%AC%20discord&color=00ACD7)](https://gofiber.io/discord) +![Test](https://img.shields.io/github/actions/workflow/status/gofiber/storage/test-valkey.yml?label=Tests) +![Security](https://img.shields.io/github/actions/workflow/status/gofiber/storage/gosec.yml?label=Security) +![Linter](https://img.shields.io/github/actions/workflow/status/gofiber/storage/linter.yml?label=Linter) + +A fast Valkey Storage that does auto pipelining and supports client side caching. Implementation is based on [valkey-io/valkey](https://github.com/valkey-io/valkey-go). + +### Table of Contents + +- [Signatures](#signatures) +- [Installation](#installation) +- [Examples](#examples) +- [Config](#config) +- [Default Config](#default-config) + +### Signatures + +```go +func New(config ...Config) Storage +func (s *Storage) Get(key string) ([]byte, error) +func (s *Storage) Set(key string, val []byte, exp time.Duration) error +func (s *Storage) Delete(key string) error +func (s *Storage) Reset() error +func (s *Storage) Close() error +func (s *Storage) Conn() valkey.Client +``` + +### Installation + +The valkey driver is tested on the latest two [Go version](https://golang.org/dl/) with support for modules. So make sure to initialize one first if you didn't do that yet: + +```bash +go mod init github.com// +``` + +And then install the valkey implementation: + +```bash +go get github.com/gofiber/storage/valkey +``` + +### Examples + +Import the storage package. + +```go +import "github.com/gofiber/storage/valkey" +``` + +You can use the one of the following options to create a Valkey Storage: + +```go +// Initialize default config (localhost:6379) +store := valkey.New() + +// Initialize custom config +store := valkey.New(valkey.Config{ + InitAddress: []string{"localhost:6380"}, + Username: "", + Password: "", + Database: 0, + Reset: false, + TLSConfig: nil, +}) + +// Initialize using Redis-style URL +store := valkey.New(valkey.Config{ + URL: "redis://localhost:6379", +}) + +// Initialize Valkey Cluster Client +store := valkey.New(valkey.Config{ + InitAddress: []string{":6379", ":6380"}, +}) + +// Create a client with support for TLS +cer, err := tls.LoadX509KeyPair("./client.crt", "./client.key") +if err != nil { + log.Println(err) + return +} +tlsCfg := &tls.Config{ + MinVersion: tls.VersionTLS12, + InsecureSkipVerify: true, + Certificates: []tls.Certificate{cer}, +} +store = valkey.New(valkey.Config{ + InitAddress: []string{"localhost:6380"}, + Username: "", + Password: "", + SelectDB: 0, + TLSConfig: tlsCfg, +}) + +``` + +### Config + +```go +type Config struct { + // Server username + // + // Optional. Default is "" + Username string + + // Server password + // + // Optional. Default is "" + Password string + + // ClientName will execute the `CLIENT SETNAME ClientName` command for each conn. + // + // Optional. Default is "" + ClientName string + + // URL standard format Redis-style URL. If this is set all other config options, InitAddress, Username, Password, ClientName, and SelectDB have no effect. + // + // Example: redis://:@localhost:6379/ + // Optional. Default is "" + URL string + + // SelectDB to be selected after connecting to the server. + // + // Optional. Default is 0 + SelectDB int + + // Either a single address or a seed list of host:port addresses, this enables FailoverClient and ClusterClient + // + // Optional. Default is []string{"127.0.0.1:6379"} + InitAddress []string + + // TLS Config to use. When set TLS will be negotiated. + // + // Optional. Default is nil + TLSConfig *tls.Config + + // CacheSizeEachConn is valkey client side cache size that bind to each TCP connection to a single valkey instance. + // + // Optional. The default is DefaultCacheBytes: 128 * (1 << 20) + CacheSizeEachConn int + + // RingScaleEachConn sets the size of the ring buffer in each connection to (2 ^ RingScaleEachConn). + // + // Optional. The default is RingScaleEachConn, which results into having a ring of size 2^10 for each connection. + RingScaleEachConn int + + // ReadBufferEachConn is the size of the bufio.NewReaderSize for each connection, default to DefaultReadBuffer (0.5 MiB). + // + // Optional. The default is DefaultReadBuffer: 1 << 19 + ReadBufferEachConn int + + // WriteBufferEachConn is the size of the bufio.NewWriterSize for each connection, default to DefaultWriteBuffer (0.5 MiB). + // + // Optional. The default is DefaultWriteBuffer: 1 << 19 + WriteBufferEachConn int + + // BlockingPoolSize is the size of the connection pool shared by blocking commands (ex BLPOP, XREAD with BLOCK). + // + // Optional. The default is DefaultPoolSize: 1000 + BlockingPoolSize int + + // PipelineMultiplex determines how many tcp connections used to pipeline commands to one valkey instance. + // + // Optional. The default for single and sentinel clients is 2, which means 4 connections (2^2). + PipelineMultiplex int + + // DisableRetry disables retrying read-only commands under network errors + // + // Optional. The default is False + DisableRetry bool + + // DisableCache falls back Client.DoCache/Client.DoMultiCache to Client.Do/Client.DoMulti + // + // Optional. The default is false + DisableCache bool + + // AlwaysPipelining makes valkey.Client always pipeline valkey commands even if they are not issued concurrently. + // + // Optional. The default is true + AlwaysPipelining bool + + // Reset clears any existing keys in existing Collection + // + // Optional. Default is false + Reset bool + + // CacheTTL TTL + // + // Optional. Default is time.Minute + CacheTTL time.Duration +} +``` + +### Default Config + +```go +var ConfigDefault = Config{ + Username: "", + Password: "", + ClientName: "", + SelectDB: 0, + InitAddress: []string{"127.0.0.1:6379"}, + TLSConfig: nil, + CacheSizeEachConn: valkey.DefaultCacheBytes, + RingScaleEachConn: valkey.DefaultRingScale, + ReadBufferEachConn: valkey.DefaultReadBuffer, + WriteBufferEachConn: valkey.DefaultWriteBuffer, + BlockingPoolSize: valkey.DefaultPoolSize, + PipelineMultiplex: 2, + DisableRetry: false, + DisableCache: false, + AlwaysPipelining: true, + Reset: false, + CacheTTL: time.Minute, +} +``` diff --git a/storage_versioned_sidebars/version-valkey_v0.x.x-sidebars.json b/storage_versioned_sidebars/version-valkey_v0.x.x-sidebars.json new file mode 100644 index 00000000000..cbf35feb3b7 --- /dev/null +++ b/storage_versioned_sidebars/version-valkey_v0.x.x-sidebars.json @@ -0,0 +1,8 @@ +{ + "left_sidebar": [ + { + "type": "autogenerated", + "dirName": "." + } + ] +} diff --git a/storage_versions.json b/storage_versions.json index 3e89bc0314f..7a746d05db6 100644 --- a/storage_versions.json +++ b/storage_versions.json @@ -1,4 +1,5 @@ [ + "valkey_v0.x.x", "sqlite3_v2.x.x", "sqlite3_v1.x.x", "scylladb_v0.x.x",