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

• Client: Wraps the Google Cloud Datastore client and provides methods for URL entity management.
• URL: Represents a URL entity within the datastore with fields for the original URL and a unique identifier.
• DatastoreError: Represents structured errors from the Datastore client, including an error code, description, and optional details or URL.

Variables

• ErrNotFound: An error representing the absence of a URL entity in the datastore.
• Logger: A package-level variable for consistent logging. It should be set using SetLogger before using logging functions.

Handler Functions

The package offers functions for datastore operations:

• CreateDatastoreClient: Initializes and returns a new datastore client.
• SaveURL: Saves a URL entity to the datastore.
• GetURL: Retrieves a URL entity from the datastore by ID.
• UpdateURL: Updates an existing URL entity in the datastore.
• DeleteURL: Deletes a URL entity from the datastore by ID.
• CloseClient: Closes the datastore client and releases resources.
• ParseDatastoreClientError: Parses errors from the Datastore client into a structured format.

Example Usage

The following example demonstrates how to initialize a datastore client, save a URL entity, and retrieve it using the package's functions:

func main() {
    logger, _ := zap.NewDevelopment()
    defer logger.Sync()

    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 func() {
        if err := datastore.CloseClient(client); err != nil {
            logger.Error("Failed to close datastore client", zap.Error(err))
        }
    }()

    // Use the client to save a new URL entity
    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 the URL entity by ID
    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))
    }
}

Concurrency

The package functions are designed for concurrent use and are safe for use by multiple goroutines.

Contexts

The CreateContext function is provided for creating new contexts for datastore operations, allowing for request lifetime control and value passing across API boundaries.

Cleanup

It is important to close the datastore client with CloseClient to release resources.

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 DatastoreError
  • func ParseDatastoreClientError(err error) (*DatastoreError, error)
  • func (e *DatastoreError) Error() string
  • func (e *DatastoreError) MarshalJSON() ([]byte, error)
• 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"
	DataStoreAuthInvalidToken     = "reauthentication required due to invalid token."

	// 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.

Note: some constants are not used in the code, indicate that for future use.

const (
	ObjCode        = "Code"
	ObjDescription = "Description"
	ObjDetails     = "Details"
)

Define error object constants.

Variables

var ErrNotFound = errors.New(DataStoreNosuchentity)

ErrNotFound is the error returned when a requested entity is not found in the datastore. This error is used to signal that a URL entity with the provided ID does not exist.

var Logger *zap.Logger

Logger is a package-level variable to access the zap logger throughout the datastore package. It can be set using the SetLogger function and is used by various functions for consistent logging.

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. The function 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 that can be used to carry deadlines, cancellation signals, and other request-scoped values across API boundaries and between processes.

func DeleteURL

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

DeleteURL deletes a URL entity by its ID from Datastore. It uses the provided context and datastore client to delete the URL entity by its unique identifier. The function 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 uses the provided context and datastore client to save the URL struct to the datastore. The function 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. This function configures the package-level Logger variable for use throughout the datastore 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 performs the update within a transaction to ensure the operation is atomic. The function 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. This allows for easier mocking and testing, as well as decoupling the code from the specific datastore client used.

func CreateDatastoreClient

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

CreateDatastoreClient creates a new client connected to Google Cloud Datastore. It initializes the connection using the provided context and configuration settings. The function returns a new Client instance or an error if the connection could not be established.

type Config

type Config struct {
	Logger    *zap.Logger // The logger for logging operations within the datastore package.
	ProjectID string      // The Google Cloud project ID where the datastore is located.
}

Config holds the configuration settings for the datastore client. This includes the logger for logging operations and the project ID for Google Cloud Datastore.

func NewConfig

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

NewConfig creates a new instance of Config with the given logger and project ID. This function is used to configure the datastore client with necessary settings.

type DatastoreError

type DatastoreError struct {
	Code        string `json:"code"`                  // The error code.
	Description string `json:"description"`           // The human-readable error description.
	Details     string `json:"Details,omitempty"`     // Additional details about the error.
	DetailsURL  string `json:"details_url,omitempty"` // A URL with more information about the error, if available.
}

DatastoreError represents a structured error for the Datastore client. It includes details about the error code, description, and any additional details or URLs related to the error.

func ParseDatastoreClientError

func ParseDatastoreClientError(err error) (*DatastoreError, error)

ParseDatastoreClientError parses the error from the Datastore client and returns a structured error. It attempts to extract meaningful information from the error returned by the datastore client and formats it into a DatastoreError. It returns the structured error and a parsing error, if any.

func (*DatastoreError) Error

func (e *DatastoreError) Error() string

Error implements the error interface for DatastoreError. This method formats the DatastoreError into a string, including the details URL if present.

func (*DatastoreError) MarshalJSON

func (e *DatastoreError) MarshalJSON() ([]byte, error)

MarshalJSON ensures that the DatastoreError is marshaled correctly. It overrides the default JSON marshaling to include only the relevant fields.

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. The struct tags specify how each field is stored in the datastore.

func GetURL

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

GetURL retrieves a URL entity by its ID from Datastore. It uses the provided context and datastore client to look up the URL entity by its unique identifier. The function returns the found URL entity or an error if the entity could not be retrieved.