Timezone

​

Overview

• Time localization
• Timezone-aware scheduling
• User time preferences

​

Installation

import "github.com/go-mizu/mizu/middlewares/timezone"

​

Quick Start

app := mizu.New()

app.Use(timezone.New())

app.Get("/time", func(c *mizu.Ctx) error {
    tz := timezone.Get(c)
    loc, _ := time.LoadLocation(tz)
    now := time.Now().In(loc)
    return c.JSON(200, map[string]string{
        "timezone": tz,
        "time":     now.Format(time.RFC3339),
    })
})

​

Configuration

​

Options

​

Examples

​

Basic Detection

app.Use(timezone.New())

​

Custom Header

app.Use(timezone.New(timezone.Options{
    Header: "X-User-Timezone",
}))

​

With Default

app.Use(timezone.New(timezone.Options{
    Default: "America/New_York",
}))

​

Client-Side Detection

// Set timezone cookie
document.cookie = `tz=${Intl.DateTimeFormat().resolvedOptions().timeZone}`;

app.Use(timezone.New(timezone.Options{
    CookieName: "tz",
}))

​

API Reference

​

Functions

// New creates timezone middleware
func New(opts ...Options) mizu.Middleware

// Get returns detected timezone
func Get(c *mizu.Ctx) string

// Location returns time.Location
func Location(c *mizu.Ctx) *time.Location

​

Common Timezones

​

Technical Details

​

Implementation

1. Context Storage: Timezone information is stored in the request context using a type-safe context key
2. Info Structure: Contains three key pieces of information:
   • Name: IANA timezone identifier (e.g., “America/New_York”)
   • Location: Parsed time.Location object for time conversions
   • Offset: UTC offset in seconds for the current time
3. Lookup Order: Configurable detection precedence via the Lookup option (default: “header,cookie,query”)
4. Validation: Invalid timezone names automatically fall back to the configured default
5. Cookie Management: Optional automatic cookie setting with configurable max age (default: 30 days)

​

Detection Flow

Request → Check Header → Check Cookie → Check Query → Default → Load Location → Store in Context

​

Helper Functions

• Get(c): Returns complete timezone info
• Location(c): Returns time.Location for time operations
• Name(c): Returns timezone name string
• Offset(c): Returns UTC offset in seconds
• Now(c): Returns current time in detected timezone

​

Convenience Constructors

• FromHeader(header): Only check specific header
• FromCookie(name): Only check specific cookie
• WithDefault(tz): Set custom default timezone

​

Best Practices

• Default to UTC for storage
• Convert to user timezone for display
• Use IANA timezone names
• Detect via JavaScript for accuracy

​

Testing

​

Related Middlewares

• language - Language detection