deckv

README

Deckv - Disposable Email Checker as a Key-Value Store for Golang

Deckv is a simple and efficient blocklist implementation for Go applications with support for multiple storage backends.

Features

• Simple and easy-to-use API
• Multiple storage backend support
  • In-memory storage (default)
  • Redis storage
• Configurable through simple text files
• Context support for all operations
• Thread-safe operations

Installation

go get github.com/salihguru/deckv

Usage

See the examples directory for more detailed usage examples.

Quick Start

Blocklist Configuration File

You can create a blocklist configuration file with the following content:

0-mail.com
1-mail.com

or real and full domain names, use this file disposable-email-domains config file as a reference.

Using In-Memory Storage

Create a blocklist.conf file with the following content:

0-mail.com
1-mail.com

bytes, err := os.ReadFile("./blocklist.conf")
if err != nil {
    panic(err)
}
client := deckv.New(deckv.WithConfFileBytes(bytes))
err := client.Load(context.Background())
if err != nil {
    panic(err)
}
isBlocked, err := client.Check(context.Background(), "0-mail.com")
if err != nil {
    panic(err)
}
fmt.Println(isBlocked)

Using Redis Storage

Create a blocklist.conf file with the following content:

0-mail.com
1-mail.com

You can use Redis storage by setting the WithStorage option.

bytes, err := os.ReadFile("./blocklist.conf")
if err != nil {
    panic(err)
}
storage := deckvredis.New(deckvredis.Config{
    Host:     "localhost",
    Port:     "6379",
    Password: "",
    DB:       0,
})
client := deckv.New(deckv.WithConfFileBytes(bytes), deckv.WithStorage(storage))
err := client.Load(context.Background())
if err != nil {
    panic(err)
}
isBlocked, err := client.Check(context.Background(), deckv.FromEmail("test@0-mail.com"))
if err != nil {
    panic(err)
}
fmt.Println(isBlocked)

Configuration File Format

The blocklist configuration file is a simple text file with one entry per line:

0-mail.com
1-mail.com

License

This project is licensed under the MIT License - see the LICENSE file for details.

Documentation

Overview

Package deckv provides a simple and efficient blocklist implementation with support for multiple storage backends.

Deckv allows you to manage and check against blocklists (e.g., email domains, IP addresses, usernames) using either in-memory storage or Redis as a backend.

Basic usage with in-memory storage:

client := deckv.New(deckv.WithConfFilePath("./blocklist.conf"))
err := client.Load(context.Background())
if err != nil {
    log.Fatal(err)
}

blocked, err := client.Check(context.Background(), "blocked-domain.com")

Using with Redis storage:

storage := deckvredis.New(context.Background(), deckvredis.Config{
    Host: "localhost",
    Port: "6379",
})
client := deckv.New(
    deckv.WithConfFilePath("./blocklist.conf"),
    deckv.WithStorage(storage),
)

Package deckv provides blocklist functionality with multiple storage backend support.

Index

• func FromEmail(email string) string
• type Client
  • func New(opts ...Option) *Client
  • func (d *Client) Check(ctx context.Context, key string) (bool, error)
  • func (d *Client) Load(ctx context.Context) error
• type Config
• type DataStorage
• type InMemStorage
  • func (s *InMemStorage) Check(ctx context.Context, key string) (bool, error)
  • func (s *InMemStorage) Save(ctx context.Context, data map[string]uint8) error
• type Option
  • func WithConfFileBytes(data []byte) Option
  • func WithStorage(storage DataStorage) Option

Functions

func FromEmail

func FromEmail(email string) string

FromEmail extracts the domain part from an email address.

Types

type Client

type Client struct {
	// contains filtered or unexported fields
}

Deckv represents the main blocklist client.

func New

func New(opts ...Option) *Client

New creates a new Deckv instance with the provided options.

func (*Client) Check

func (d *Client) Check(ctx context.Context, key string) (bool, error)

Check verifies if the provided key exists in the blocklist. Returns true if the key is blocked, false otherwise.

func (*Client) Load

func (d *Client) Load(ctx context.Context) error

Load reads the blocklist from the configured file and stores it in the configured storage. If no configuration file path or storage is set, this operation is a no-op.

type Config

type Config struct {
	ConfigFileBytes []byte
	Storage         DataStorage
}

Config holds the configuration for Deckv instance.

type DataStorage

type DataStorage interface {
	// Save stores the provided blocklist data in the storage backend.
	Save(ctx context.Context, data map[string]uint8) error
	// Check verifies if a key exists in the storage backend.
	Check(ctx context.Context, key string) (bool, error)
}

DataStorage defines the interface for blocklist storage backends.

type InMemStorage

type InMemStorage struct {
	// contains filtered or unexported fields
}

InMemStorage implements DataStorage interface using in-memory storage.

func (*InMemStorage) Check

func (s *InMemStorage) Check(ctx context.Context, key string) (bool, error)

Check verifies if a key exists in the in-memory storage.

func (*InMemStorage) Save

func (s *InMemStorage) Save(ctx context.Context, data map[string]uint8) error

Save stores the blocklist data in memory.

type Option

type Option func(*Config)

Option defines a function type for configuring Deckv instances.

func WithConfFileBytes

func WithConfFileBytes(data []byte) Option

WithConfFileBytes sets the blocklist configuration file content as bytes. This is the preferred method for providing configuration to avoid file path security issues.

func WithStorage

func WithStorage(storage DataStorage) Option

WithStorage sets the storage backend to use for the blocklist.