anvil

func CORS ¶

func CORS(origins []string, methods []string, allowCredentials bool) *cors.Cors

CORS creates a new CORS middleware with the specified configuration. This function creates a CORS handler that can be used to handle Cross-Origin Resource Sharing requests. It configures which origins, methods, and credentials are allowed for cross-origin requests.

Example usage:

corsHandler := CORS([]string{"https://example.com"}, []string{"GET", "POST"}, true)
handler := PopulateHandlerWithCORS(corsHandler, myHandler)

Parameters:

• origins: List of allowed origin URLs (e.g., ["https://example.com"])
• methods: List of allowed HTTP methods (e.g., ["GET", "POST", "PUT"])
• allowCredentials: Whether to allow credentials in cross-origin requests

Returns:

• *cors.Cors: A configured CORS middleware handler

func ClerkAuthMiddleware ¶

func ClerkAuthMiddleware(clerk clerk.Client) func(next http.Handler) http.Handler

func ClerkWebhookMiddleware ¶

func ClerkWebhookMiddleware(clerk clerk.Client, secret string) func(next http.Handler) http.Handler

func GenerateHashString ¶

func GenerateHashString(input string) (string, error)

GenerateHashString creates a secure hash of the input string using Argon2id. This function uses the Argon2id variant, which is recommended for password hashing due to its resistance to both GPU-based attacks and side-channel attacks.

The function generates a cryptographically secure random salt and applies the Argon2id algorithm with the following parameters:

• Memory: 64 MiB (64 * 1024 KiB)
• Iterations: 3
• Parallelism: 2 threads
• Salt length: 16 bytes
• Key length: 32 bytes

The returned hash string follows the standard Argon2 format:

$argon2id$v=19$m=65536,t=3,p=2$[salt]$[hash]

Example usage:

hash, err := GenerateHashString("myPassword123")
if err != nil {
    // handle error
}
// Store hash in database

Parameters:

• input: The string to hash (typically a password)

Returns:

• string: The encoded hash string in Argon2 format
• error: Any error that occurred during hashing (e.g., crypto/rand failure)

func GenerateNamespaceUUID ¶

func GenerateNamespaceUUID(namespace string) string

GenerateNamespaceUUID creates a UUID with a namespace suffix. This function generates a standard UUID and appends the provided namespace to create a namespaced identifier. This is useful for creating unique identifiers that are scoped to a specific context or domain.

The generated UUID follows the standard UUID v4 format, and the namespace is appended with a hyphen separator. This creates identifiers that are both globally unique and contextually meaningful.

Example usage:

userID := GenerateNamespaceUUID("user")
// Result: "550e8400-e29b-41d4-a716-446655440000-user"

orderID := GenerateNamespaceUUID("order")
// Result: "550e8400-e29b-41d4-a716-446655440000-order"

Parameters:

• namespace: The namespace to append to the UUID

Returns:

• string: A namespaced UUID string

func GenerateUUID ¶

func GenerateUUID() string

GenerateUUID creates a new random UUID (Universally Unique Identifier). This function generates a version 4 UUID using the crypto/rand package, ensuring cryptographic randomness and uniqueness. UUIDs are useful for creating globally unique identifiers for database records, API endpoints, and other resources that need to be uniquely identified.

The generated UUID follows the standard format: xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx where x is a hexadecimal digit and y is one of 8, 9, A, or B.

Example usage:

id := GenerateUUID()
// Result: "550e8400-e29b-41d4-a716-446655440000"

Returns:

• string: A new random UUID string

func GetCurrentDate ¶

func GetCurrentDate() time.Time

GetCurrentDate returns the current date at midnight UTC. This function returns a time.Time value representing the current date with the time set to 00:00:00 UTC. This is useful for date-based operations where you need to work with dates without time components, such as date ranges, daily statistics, or date-based filtering.

The function extracts the year, month, and day from the current time and creates a new time.Time value with those components and zero time.

Example usage:

today := GetCurrentDate()
// Result: 2024-01-15 00:00:00 +0000 UTC

Returns:

• time.Time: The current date at midnight UTC

func GetFutureDate ¶

func GetFutureDate(years int, months int, days int) time.Time

GetFutureDate calculates a future date based on the specified offsets. This function adds the specified number of years, months, and days to the current date and returns the resulting future date. This is useful for calculating expiration dates, subscription end dates, or other future time-based events.

The function uses time.AddDate which properly handles month and year boundaries, including leap years and varying month lengths.

Example usage:

// Get date 1 year, 6 months, and 15 days from now
futureDate := GetFutureDate(1, 6, 15)
// Result: Current date + 1 year + 6 months + 15 days

// Get date 2 years from now
twoYearsFromNow := GetFutureDate(2, 0, 0)

Parameters:

• years: Number of years to add (can be negative for past dates)
• months: Number of months to add (can be negative)
• days: Number of days to add (can be negative)

Returns:

• time.Time: The calculated future date

func HandlerFunc ¶

func HandlerFunc(f APIFunc) http.HandlerFunc

HandlerFunc converts an APIFunc to a standard http.HandlerFunc with automatic error handling. This function wraps API handlers to provide consistent error response formatting. When the wrapped function returns an error, it automatically calls RespondWithError to send a properly formatted JSON error response to the client.

Example usage:

http.HandleFunc("/api/users", HandlerFunc(createUserHandler))

Parameters:

• f: The APIFunc to wrap with error handling

Returns:

• http.HandlerFunc: A standard HTTP handler function with error handling

func IsMatchingInputAndHash ¶

func IsMatchingInputAndHash(input, encodedHash string) (match bool, err error)

IsMatchingInputAndHash verifies if an input string matches a previously generated hash. This function safely compares the input string against a stored hash using constant-time comparison to prevent timing attacks.

The function:

1. Decodes the stored hash to extract parameters, salt, and hash
2. Generates a new hash using the same parameters and salt
3. Compares the hashes using constant-time comparison

This function is typically used for password verification during login.

Example usage:

match, err := IsMatchingInputAndHash("myPassword123", storedHash)
if err != nil {
    // handle error (invalid hash format, incompatible version, etc.)
}
if match {
    // password is correct
} else {
    // password is incorrect
}

Parameters:

• input: The string to verify (typically a password)
• encodedHash: The previously generated hash string to compare against

Returns:

• bool: true if the input matches the hash, false otherwise
• error: Any error that occurred during verification (e.g., invalid hash format)

func LoggerMiddleware ¶

func LoggerMiddleware(next http.Handler) http.Handler

LoggerMiddleware creates an HTTP middleware that logs request information. This middleware extracts and logs the client's IP address, host, server address, user agent, and request details (method, path, remote address) for each HTTP request. The logging is done using the structured logging package (slog) for better log parsing.

The middleware logs the following information:

• IP address of the client
• Host from the request URL
• Server address
• User agent string
• Request method, path, and remote address

Example usage:

http.Handle("/api", LoggerMiddleware(myHandler))

Parameters:

• next: The next HTTP handler in the middleware chain

Returns:

• http.Handler: A new handler that logs requests before passing them to the next handler

func PopulateHandlerWithCORS ¶

func PopulateHandlerWithCORS(crossOrigin *cors.Cors, handler http.Handler) http.Handler

PopulateHandlerWithCORS wraps an HTTP handler with CORS middleware. This function applies CORS configuration to an existing HTTP handler, enabling cross-origin requests according to the specified CORS settings.

The CORS middleware will be applied to all requests handled by the provided handler, adding the necessary CORS headers to responses based on the CORS configuration.

Example usage:

corsHandler := CORS([]string{"https://example.com"}, []string{"GET", "POST"}, true)
finalHandler := PopulateHandlerWithCORS(corsHandler, myHandler)
http.Handle("/api", finalHandler)

Parameters:

• crossOrigin: The CORS configuration to apply
• handler: The HTTP handler to wrap with CORS middleware

Returns:

• http.Handler: A new handler with CORS middleware applied

func RateLimitInternal ¶

func RateLimitInternal(next http.Handler) http.Handler

RateLimitInternal creates middleware that applies internal API rate limiting. This middleware uses the RateLimitInternalAPI configuration, which allows 10000 requests per second with a burst capacity of 200 requests. It's suitable for internal service-to-service communication.

The middleware tracks clients by IP address and applies rate limiting per client. When a client exceeds the rate limit, it receives a 429 (Too Many Requests) response with a JSON error message.

Example usage:

http.Handle("/api/internal", RateLimitInternal(myHandler))

Parameters:

• next: The next HTTP handler in the middleware chain

Returns:

• http.Handler: A new handler that applies internal API rate limiting

func RateLimitPublic ¶

func RateLimitPublic(next http.Handler) http.Handler

RateLimitPublic creates middleware that applies public API rate limiting. This middleware uses the RateLimitPublicAPI configuration, which allows 5000 requests per second with a burst capacity of 100 requests. It's suitable for public-facing endpoints that need to handle high traffic.

The middleware tracks clients by IP address and applies rate limiting per client. When a client exceeds the rate limit, it receives a 429 (Too Many Requests) response with a JSON error message.

Example usage:

http.Handle("/api/public", RateLimitPublic(myHandler))

Parameters:

• next: The next HTTP handler in the middleware chain

Returns:

• http.Handler: A new handler that applies public API rate limiting

func RateLimitStrict ¶

func RateLimitStrict(next http.Handler) http.Handler

RateLimitStrict creates middleware that applies strict API rate limiting. This middleware uses the RateLimitStrictAPI configuration, which allows 100 requests per second with a burst capacity of 10 requests. It's suitable for sensitive endpoints like authentication or payment processing.

The middleware tracks clients by IP address and applies rate limiting per client. When a client exceeds the rate limit, it receives a 429 (Too Many Requests) response with a JSON error message.

Example usage:

http.Handle("/api/auth", RateLimitStrict(myHandler))

Parameters:

• next: The next HTTP handler in the middleware chain

Returns:

• http.Handler: A new handler that applies strict API rate limiting

func RateLimitWeb ¶

func RateLimitWeb(next http.Handler) http.Handler

RateLimitWeb creates middleware that applies user web API rate limiting. This middleware uses the RateLimitUserWebAPI configuration, which allows 300 requests per second with a burst capacity of 30 requests. It's suitable for web applications where users interact directly with the API.

The middleware tracks clients by IP address and applies rate limiting per client. When a client exceeds the rate limit, it receives a 429 (Too Many Requests) response with a JSON error message.

Example usage:

http.Handle("/api/web", RateLimitWeb(myHandler))

Parameters:

• next: The next HTTP handler in the middleware chain

Returns:

• http.Handler: A new handler that applies user web API rate limiting

func RespondWithError ¶

func RespondWithError(w http.ResponseWriter, e error) error

RespondWithError sends a JSON error response to the client. This function formats the error message and includes a timestamp in the response. It automatically sets the HTTP status code to 400 (Bad Request) and the Content-Type header to application/json.

The error response follows this structure:

{
  "error": "error message here",
  "timestamp": "2024-01-01 12:00:00 +0000 UTC"
}

Parameters:

• w: The HTTP response writer
• e: The error to format and send

Returns:

• error: Any error that occurred during response writing

func RespondWithSuccess ¶

func RespondWithSuccess(w http.ResponseWriter, status int, v any) error

RespondWithSuccess sends a JSON success response to the client. This function sends the provided data as JSON with the specified HTTP status code. It automatically sets the Content-Type header to application/json.

Parameters:

• w: The HTTP response writer
• status: The HTTP status code to return (e.g., 200, 201, 204)
• v: The data to encode as JSON in the response body

Returns:

• error: Any error that occurred during JSON encoding or writing

func SafeBool ¶

func SafeBool(data map[string]interface{}, key string) bool

SafeBool safely extracts a boolean value from a map[string]interface{}. This function provides type-safe access to boolean values in maps that contain mixed types (interface{}). It handles cases where the key doesn't exist, the value is nil, or the value is not a boolean type.

The function returns false if:

• The key doesn't exist in the map
• The value is nil
• The value is not a boolean type

This is useful when working with JSON data, database results, or any map that contains mixed data types and you need to safely extract boolean values without causing panics.

Example usage:

data := map[string]interface{}{
    "active": true,
    "verified": false,
    "email": nil,
    "name": "John",
}
active := SafeBool(data, "active")     // Returns: true
verified := SafeBool(data, "verified") // Returns: false
email := SafeBool(data, "email")       // Returns: false
missing := SafeBool(data, "missing")   // Returns: false

Parameters:

• data: The map containing mixed data types
• key: The key to look up in the map

Returns:

• bool: The boolean value if found and valid, false otherwise

func SafeString ¶

func SafeString(data map[string]interface{}, key string) string

SafeString safely extracts a string value from a map[string]interface{}. This function provides type-safe access to string values in maps that contain mixed types (interface{}). It handles cases where the key doesn't exist, the value is nil, or the value is not a string type.

The function returns an empty string if:

• The key doesn't exist in the map
• The value is nil
• The value is not a string type

This is useful when working with JSON data, database results, or any map that contains mixed data types and you need to safely extract string values without causing panics.

Example usage:

data := map[string]interface{}{
    "name": "John",
    "age":  30,
    "email": nil,
}
name := SafeString(data, "name")     // Returns: "John"
email := SafeString(data, "email")   // Returns: ""
missing := SafeString(data, "missing") // Returns: ""

Parameters:

• data: The map containing mixed data types
• key: The key to look up in the map

Returns:

• string: The string value if found and valid, empty string otherwise

func SafeTime ¶

func SafeTime(data map[string]interface{}, key string) time.Time

SafeTime safely extracts a time.Time value from a map[string]interface{}. This function provides type-safe access to time.Time values in maps that contain mixed types (interface{}). It handles cases where the key doesn't exist, the value is nil, or the value is not a time.Time type.

The function returns the zero value of time.Time if:

• The key doesn't exist in the map
• The value is nil
• The value is not a time.Time type

This is useful when working with JSON data, database results, or any map that contains mixed data types and you need to safely extract time values without causing panics.

Example usage:

data := map[string]interface{}{
    "created_at": time.Now(),
    "updated_at": nil,
    "name": "John",
}
createdAt := SafeTime(data, "created_at") // Returns: actual time
updatedAt := SafeTime(data, "updated_at") // Returns: zero time
missing := SafeTime(data, "missing")      // Returns: zero time

Parameters:

• data: The map containing mixed data types
• key: The key to look up in the map

Returns:

• time.Time: The time.Time value if found and valid, zero time otherwise