Cloudflare KV
A Cloudflare KV storage driver using cloudflare/cloudflare-go.
Table of Contents
Signatures
func New(config ...Config) Storage
func NewFromConnection(api APIInterface, config ...Config) *Storage
func (s *Storage) Get(key string) ([]byte, error)
func (s *Storage) GetWithContext(ctx context.Context, key string) ([]byte, error)
func (s *Storage) Set(key string, val []byte, exp time.Duration) error
func (s *Storage) SetWithContext(ctx context.Context, key string, val []byte, exp time.Duration) error
func (s *Storage) Delete(key string) error
func (s *Storage) DeleteWithContext(ctx context.Context, key string) error
func (s *Storage) Reset() error
func (s *Storage) ResetWithContext(ctx context.Context) error
func (s *Storage) Close() error
func (s *Storage) Conn() *cloudflare.API
Installation
go mod init github.com/<user>/<repo>
And then install the Cloudflare KV implementation:
go get github.com/gofiber/storage/cloudflarekv
Examples
Import the storage package.
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 documentation to generate one.
// Initialize default config
store := cloudflarekv.New()
store := cloudflarekv.New(cloudflarekv.Config{
Key: "",
Email: "",
AccountID: "fiber",
NamespaceID: "fiber",
RequestTimeout: 10 * time.Second,
Reset: false,
})
Config
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
// RequestTimeout bounds each API call whose context has no deadline, including the wait
// for the client's rate limiter. A negative value disables it.
//
// Optional. Default is 10 seconds
RequestTimeout time.Duration
// Reset clears any existing keys in existing Table
//
// Optional. Default is false
Reset bool
}
Default Config
var ConfigDefault = Config{
Key: "",
Email: "",
AccountID: "fiber",
NamespaceID: "fiber",
RequestTimeout: 10 * time.Second,
Reset: false,
}
Notes
- A non-zero expiration passed to
Setbecomes the key'sexpiration_ttl. Workers KV accepts no TTL under 60 seconds, so shorter expirations are rounded up to 60 seconds: an entry may outlive a short expiration, but never expires early. Keys written by earlier versions of this driver have no TTL and never expire; to drop them, clear the namespace (for example withReset) once every instance runs this version. Getreturnsnil, nilfor a missing or expired key. Workers KV cannot store the keys.and.., soGetandDeletetreat them as missing andSetreturnsErrInvalidKey. A wrongNamespaceIDalso looks like a miss onGet, whileSet,DeleteandResetreturn the API error.cloudflare-gosends all calls of a client through one rate limiter (4 requests per second by default).RequestTimeoutbounds the wait: a call that would not get a slot in time fails at once instead of queueing without limit. If your account allows more, build the client withcloudflare.UsingRateLimitand pass it toNewFromConnection.
Using an Existing Cloudflare API Client
If your application already holds a Cloudflare API client, you can build the storage on it instead of creating a second one. Only the Email, AccountID, NamespaceID, RequestTimeout and Reset options are read; the credentials come from the client. A custom APIInterface must also implement Raw, which *cloudflare.API provides.
The client stays yours to manage: Close on a storage built this way is a no-op, so the rest of your application keeps working.
import (
"github.com/cloudflare/cloudflare-go"
"github.com/gofiber/storage/cloudflarekv"
)
func main() {
api, err := cloudflare.NewWithAPIToken("token")
if err != nil {
panic(err)
}
store := cloudflarekv.NewFromConnection(api, cloudflarekv.Config{
AccountID: "account-id",
NamespaceID: "namespace-id",
})
defer store.Close()
}