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.

The package encapsulates the complexity of direct datastore interactions and offers a simplified API for the rest of the application. It also integrates structured logging using the zap library, which allows for consistent and searchable log entries across the service.

Usage example:

func main() {
    ctx := datastore.CreateContext()
    client, err := datastore.CreateDatastoreClient(ctx, "my-project-id")
    if err != nil {
        log.Fatalf("Failed to create datastore client: %v", 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 {
        log.Fatalf("Failed to save URL: %v", err)
    }

    // Retrieve, update, or delete URLs as needed
}

The package also defines a custom `URL` type that represents a URL entity within the datastore. This type is used for all operations that involve URL entities.

The `Client` type wraps the Google Cloud Datastore client, providing a layer of abstraction that allows for mocking and testing without relying on an actual datastore instance.

The `SetLogger` function allows for the injection of a zap logger instance, which is used throughout the package to log operations and errors. This ensures that any issues or actions are logged in a format that is consistent with the rest of the URL shortener service.

Error handling is a critical aspect of the package. The `ErrNotFound` variable is returned when a requested entity is not found in the datastore, allowing calling code to distinguish between different types of errors and handle them accordingly.

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 H0llyW00dzZ

Index

• 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, projectID string) (*Client, error)
• type URL
  • func GetURL(ctx context.Context, dsClient *Client, id string) (*URL, error)

Variables

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

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, projectID string) (*Client, error)

CreateDatastoreClient creates a new client connected to Google Cloud Datastore. It requires a context and a projectID to initialize the connection. Returns a new Datastore client or an error if the connection could not be established.

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.