From 0d24ef0d604c21000366feecde8010fa64cc04e5 Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" Date: Thu, 9 Jan 2025 09:48:25 +0000 Subject: [PATCH] Sync docs for release https://github.com/gofiber/storage/releases/tag/coherence/v1.2.3 --- .../version-coherence_v1.x.x/README.md | 2 + .../clickhouse/README.md | 123 ++++++++++ .../coherence/README.md | 6 +- .../version-coherence_v1.x.x/minio/README.md | 5 + .../version-coherence_v1.x.x/nats/README.md | 66 +++--- .../postgres/README.md | 2 +- .../version-coherence_v1.x.x/valkey/README.md | 222 ++++++++++++++++++ .../version-coherence_v1.x.x-sidebars.json | 2 +- 8 files changed, 388 insertions(+), 40 deletions(-) create mode 100644 storage_versioned_docs/version-coherence_v1.x.x/clickhouse/README.md create mode 100644 storage_versioned_docs/version-coherence_v1.x.x/valkey/README.md diff --git a/storage_versioned_docs/version-coherence_v1.x.x/README.md b/storage_versioned_docs/version-coherence_v1.x.x/README.md index 532bebabf3e..79d51567024 100644 --- a/storage_versioned_docs/version-coherence_v1.x.x/README.md +++ b/storage_versioned_docs/version-coherence_v1.x.x/README.md @@ -74,3 +74,5 @@ type Storage interface { - [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-coherence_v1.x.x/clickhouse/README.md b/storage_versioned_docs/version-coherence_v1.x.x/clickhouse/README.md new file mode 100644 index 00000000000..8efab4d732b --- /dev/null +++ b/storage_versioned_docs/version-coherence_v1.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-coherence_v1.x.x/coherence/README.md b/storage_versioned_docs/version-coherence_v1.x.x/coherence/README.md index f4d12aaeb7c..14f7c264343 100644 --- a/storage_versioned_docs/version-coherence_v1.x.x/coherence/README.md +++ b/storage_versioned_docs/version-coherence_v1.x.x/coherence/README.md @@ -1,5 +1,5 @@ # Coherence - + A Coherence storage driver using [https://github.com/oracle/coherence-go-client](https://github.com/oracle/coherence-go-client). ### Table of Contents @@ -35,10 +35,10 @@ 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 +docker run -d -p 1408:1408 ghcr.io/oracle/coherence-ce:24.09 ``` -See the documentation [here](https://pkg.go.dev/github.com/oracle/coherence-go-client/coherence#hdr-Obtaining_a_Session) on connection options +See the documentation [here](https://pkg.go.dev/github.com/oracle/coherence-go-client/v2@v2.0.0/coherence#hdr-Obtaining_a_Session) on connection options when creating a Coherence session. ### Examples diff --git a/storage_versioned_docs/version-coherence_v1.x.x/minio/README.md b/storage_versioned_docs/version-coherence_v1.x.x/minio/README.md index 0bbc9480d0d..9c291f2de25 100644 --- a/storage_versioned_docs/version-coherence_v1.x.x/minio/README.md +++ b/storage_versioned_docs/version-coherence_v1.x.x/minio/README.md @@ -94,6 +94,10 @@ type Config struct { // 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 @@ -124,6 +128,7 @@ var ConfigDefault = Config{ Token: "", Secure: false, Reset: false, + Credentials: Credentials{}, GetObjectOptions: minio.GetObjectOptions{}, PutObjectOptions: minio.PutObjectOptions{}, diff --git a/storage_versioned_docs/version-coherence_v1.x.x/nats/README.md b/storage_versioned_docs/version-coherence_v1.x.x/nats/README.md index 8955fd56ea4..8e383a383b4 100644 --- a/storage_versioned_docs/version-coherence_v1.x.x/nats/README.md +++ b/storage_versioned_docs/version-coherence_v1.x.x/nats/README.md @@ -12,7 +12,7 @@ title: Nats A NATS Key/Value storage driver. -**Note: Requires Go 1.20 and above** +## Note: Requires Go 1.20 and above ### Table of Contents @@ -57,7 +57,7 @@ Import the storage package. import "github.com/gofiber/storage/nats" ``` -You can use the following possibilities to create a storage: +You can use the following options to create a storage driver: ```go // Initialize default config @@ -65,16 +65,16 @@ 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, - }, + 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, + }, }) ``` @@ -82,22 +82,18 @@ store := nats.New(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 - // Logger. Using Fiber AllLogger interface for adapting the various log libraries. - Logger log.AllLogger - // Use the Logger for nats events, default: false - Verbose bool - // Wait for connection to be established, default: 100ms - WaitForConnection time.Duration + // 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 } ``` @@ -105,12 +101,12 @@ type Config struct { ```go var ConfigDefault = Config{ - URLs: nats.DefaultURL, - Context: context.Background(), - ClientName: "fiber_storage", - KeyValueConfig: jetstream.KeyValueConfig{ - Bucket: "fiber_storage", - }, - WaitForConnection: 100 * time.Millisecond, + 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-coherence_v1.x.x/postgres/README.md b/storage_versioned_docs/version-coherence_v1.x.x/postgres/README.md index 04cbe4ce2a9..23ea62b828d 100644 --- a/storage_versioned_docs/version-coherence_v1.x.x/postgres/README.md +++ b/storage_versioned_docs/version-coherence_v1.x.x/postgres/README.md @@ -11,7 +11,7 @@ title: Postgres A Postgres storage driver using [jackc/pgx](https://github.com/jackc/pgx). -**Note: Requires Go 1.19 and above** +**Note: Requires Go 1.20 and above** ### Table of Contents - [Signatures](#signatures) diff --git a/storage_versioned_docs/version-coherence_v1.x.x/valkey/README.md b/storage_versioned_docs/version-coherence_v1.x.x/valkey/README.md new file mode 100644 index 00000000000..c87e2781081 --- /dev/null +++ b/storage_versioned_docs/version-coherence_v1.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-coherence_v1.x.x-sidebars.json b/storage_versioned_sidebars/version-coherence_v1.x.x-sidebars.json index caea0c03ba6..cbf35feb3b7 100644 --- a/storage_versioned_sidebars/version-coherence_v1.x.x-sidebars.json +++ b/storage_versioned_sidebars/version-coherence_v1.x.x-sidebars.json @@ -1,5 +1,5 @@ { - "tutorialSidebar": [ + "left_sidebar": [ { "type": "autogenerated", "dirName": "."