datastore

Documentation

Overview

Package datastore provides a set of tools to interact with Google Cloud Datastore. It abstracts datastore operations such as creating a client, saving, retrieving, updating, and deleting URL entities. It is designed to work with the URL shortener service to manage shortened URLs and their corresponding original URLs.

Types:

The Client type is a wrapper around the Google Cloud Datastore client that provides additional methods for URL entity management. It abstracts away the underlying datastore implementation details.

type Client struct {
    *cloudDatastore.Client
}

The URL type represents a URL entity within the datastore, with fields for the original URL and a unique identifier.

type URL struct {
    Original string `datastore:"original"` // The original URL.
    ID       string `datastore:"id"`       // The unique identifier for the shortened URL.
}

Variables:

The package exposes an ErrNotFound variable, which is an error that represents the absence of a URL entity in the datastore.

var ErrNotFound = errors.New("no such entity")

The package also includes a package-level Logger variable, which is intended to be used across the datastore package for consistent logging.

var Logger *zap.Logger

Handlers Functions:

The package provides functions to handle datastore operations. These functions include creating a new client, saving, retrieving, updating, and deleting URL entities.

func CreateDatastoreClient(ctx context.Context, config *Config) (*Client, error)
func SaveURL(ctx context.Context, client *Client, url *URL) error
func GetURL(ctx context.Context, client *Client, id string) (*URL, error)
func UpdateURL(ctx context.Context, client *Client, id string, newURL string) error
func DeleteURL(ctx context.Context, client *Client, id string) error
func CloseClient(client *Client) error

Example of package usage:

func main() {
    logger, _ := zap.NewDevelopment()
    ctx := datastore.CreateContext()
    config := datastore.NewConfig(logger, "my-project-id")
    client, err := datastore.CreateDatastoreClient(ctx, config)
    if err != nil {
        logger.Fatal("Failed to create datastore client", zap.Error(err))
    }
    defer datastore.CloseClient(client)

    // Use the client to interact with the datastore
    url := &datastore.URL{Original: "https://example.com", ID: "abc123"}
    if err := datastore.SaveURL(ctx, client, url); err != nil {
        logger.Fatal("Failed to save URL", zap.Error(err))
    }

    // Retrieve, update, or delete URLs as needed
    retrievedURL, err := datastore.GetURL(ctx, client, "abc123")
    if err != nil {
        logger.Error("Failed to retrieve URL", zap.Error(err))
    } else {
        logger.Info("Retrieved URL", zap.String("original", retrievedURL.Original))
    }
}

The package functions are designed to be used in a concurrent environment and are safe for use by multiple goroutines.

The CreateContext function is provided to create a new context for datastore operations, which can be used to control the lifetime of requests and to pass cancellation signals and other request-scoped values across API boundaries.

It is important to close the datastore client when it is no longer needed by calling the CloseClient function to release any resources associated with the client.

Copyright (c) 2023 by H0llyW00dzZ

Index

• Constants
• Variables
• func CloseClient(client *Client) error
• func CreateContext() context.Context
• func DeleteURL(ctx context.Context, client *Client, id string) error
• func SaveURL(ctx context.Context, client *Client, url *URL) error
• func SetLogger(logger *zap.Logger)
• func UpdateURL(ctx context.Context, client *Client, id string, newURL string) error
• type Client
  • func CreateDatastoreClient(ctx context.Context, config *Config) (*Client, error)
• type Config
  • func NewConfig(logger *zap.Logger, projectID string) *Config
• type URL
  • func GetURL(ctx context.Context, dsClient *Client, id string) (*URL, error)

Constants

const (
	DataStoreNosuchentity         = "datastore: no such entity"
	DataStoreFailedtoCreateClient = "Failed to create client"
	DataStoreFailedtoSaveURL      = "Failed to save URL"
	DataStoreFailedtoGetURL       = "Failed to get URL"
	DataStoreFailedtoUpdateURL    = "Failed to update URL"
	DataStoreFailedtoDeleteURL    = "Failed to delete URL"
	DataStoreFailedToCloseClient  = "Failed to close client"

	// DataStoreNameKey is the name of the Kind in Datastore for URL entities.
	// Defining it here enables changing the Kind name in one place if needed.
	DataStoreNameKey = "urlz"

	// URL Info Messages
	InfoAttemptingToUpdateURLInDatastore = "Attempting to update URL in Datastore"
	InfoFailedToUpdateURLInDatastore     = "Failed to update URL in Datastore"
	InfoUpdateSuccessful                 = "URL updated successfully in the datastore"
)

Define datastore constants. This is used to identify the component that is logging the message. Easy Maintenance: If the error message changes, it only need to change it in one place.

Variables

var ErrNotFound = errors.New(DataStoreNosuchentity)

ErrNotFound is the error returned when a requested entity is not found in the datastore.

var Logger *zap.Logger

Logger is a package-level variable to access the zap logger throughout the datastore package. It is intended to be used by other functions within the package for logging purposes.

Functions

func CloseClient

func CloseClient(client *Client) error

CloseClient closes the Datastore client. It should be called to clean up resources and connections when the client is no longer needed. Returns an error if the client could not be closed.

func CreateContext

func CreateContext() context.Context

CreateContext creates a new context that can be used for Datastore operations. It returns a non-nil, empty context.

func DeleteURL

func DeleteURL(ctx context.Context, client *Client, id string) error

DeleteURL deletes a URL entity by its ID from Datastore. It requires a context, a Datastore client, and the ID of the URL entity. Returns an error if the entity could not be deleted.

func SaveURL

func SaveURL(ctx context.Context, client *Client, url *URL) error

SaveURL saves a new URL entity to Datastore under the Kind 'urlz'. It takes a context, a Datastore client, and a URL struct. If the Kind 'urlz' does not exist, Datastore will create it automatically. Returns an error if the URL entity could not be saved.

func SetLogger

func SetLogger(logger *zap.Logger)

SetLogger sets the logger instance for the package.

func UpdateURL

func UpdateURL(ctx context.Context, client *Client, id string, newURL string) error

UpdateURL updates an existing URL entity in Datastore with a new URL. It requires a context, a Datastore client, the ID of the URL entity, and the new URL to update. Returns an error if the URL entity could not be updated.

Types

type Client

type Client struct {
	*cloudDatastore.Client
}

Client wraps the cloudDatastore.Client to abstract away the underlying implementation.

func CreateDatastoreClient

func CreateDatastoreClient(ctx context.Context, config *Config) (*Client, error)

CreateDatastoreClient creates a new client connected to Google Cloud Datastore. It requires a context and a Config struct to initialize the connection. It returns a new Datastore client wrapped in a custom Client type or an error if the connection could not be established.

type Config

type Config struct {
	Logger    *zap.Logger
	ProjectID string
}

Config holds the configuration settings for the datastore client.

func NewConfig

func NewConfig(logger *zap.Logger, projectID string) *Config

NewConfig creates a new instance of Config with the given logger and project ID.

type URL

type URL struct {
	Original string `datastore:"original"` // The original URL.
	ID       string `datastore:"id"`       // The unique identifier for the shortened URL.
}

URL represents a shortened URL with its original URL and a unique identifier.

func GetURL

func GetURL(ctx context.Context, dsClient *Client, id string) (*URL, error)

GetURL retrieves a URL entity by its ID from Datastore. It requires a context, a Datastore client, and the ID of the URL entity. Returns the URL entity or an error if the entity could not be retrieved.