Merge pull request #60 from LerianStudio/feature/limits-by-period-pr1-migrations-model-foundation

feat: database migrations and model foundation for limits by period

Author: alexgarzao

migrations/000006_add_limit_type_enum_values.down.sql

@@ -0,0 +1,21 @@
+-- ============================================
+-- Migration: 000006_add_limit_type_enum_values (DOWN)
+-- Description: Note about enum value removal
+-- Date: 2026-03-10
+-- ============================================
+-- Note: PostgreSQL does not support removing enum values directly.
+-- Removing WEEKLY and CUSTOM would require:
+-- 1. Creating a new enum without these values
+-- 2. Updating all tables using the enum
+-- 3. Dropping the old enum
+-- 4. Renaming the new enum
+--
+-- This is intentionally left as a no-op because:
+-- - Removing enum values is a breaking change
+-- - Any existing limits using WEEKLY/CUSTOM would become invalid
+-- - The risk of data loss outweighs the benefit of a clean rollback
+--
+-- If rollback is truly needed, manual intervention is required.
+DO $$ BEGIN
+  RAISE NOTICE 'Enum values WEEKLY and CUSTOM cannot be automatically removed from limit_type_enum';
+END $$;

migrations/000006_add_limit_type_enum_values.up.sql

@@ -0,0 +1,15 @@
+-- ============================================
+-- Migration: 000006_add_limit_type_enum_values
+-- Description: Add WEEKLY and CUSTOM values to limit_type_enum
+-- Date: 2026-03-10
+-- ============================================
+-- Note: Adding enum values must be in a separate migration from column changes
+-- PostgreSQL requires ADD VALUE to be the only statement in a transaction when
+-- NOT using IF NOT EXISTS (prior to PG 10), and golang-migrate handles each file
+-- as a separate transaction.
+
+-- Add WEEKLY type for limits that reset every Monday at 00:00 UTC
+ALTER TYPE limit_type_enum ADD VALUE IF NOT EXISTS 'WEEKLY';
+
+-- Add CUSTOM type for limits with user-defined periods
+ALTER TYPE limit_type_enum ADD VALUE IF NOT EXISTS 'CUSTOM';

migrations/000007_add_limit_period_columns.down.sql

@@ -0,0 +1,22 @@
+-- ============================================
+-- Migration: 000007_add_limit_period_columns (DOWN)
+-- Description: Remove time window and custom period columns from limits table
+-- Date: 2026-03-10
+-- ============================================
+
+-- Drop index first
+DROP INDEX IF EXISTS idx_limits_custom_period;
+
+-- Drop constraints
+ALTER TABLE limits DROP CONSTRAINT IF EXISTS chk_limits_time_format_end;
+ALTER TABLE limits DROP CONSTRAINT IF EXISTS chk_limits_time_format_start;
+ALTER TABLE limits DROP CONSTRAINT IF EXISTS chk_limits_custom_dates_order;
+ALTER TABLE limits DROP CONSTRAINT IF EXISTS chk_limits_custom_dates_forbidden;
+ALTER TABLE limits DROP CONSTRAINT IF EXISTS chk_limits_custom_dates_required;
+ALTER TABLE limits DROP CONSTRAINT IF EXISTS chk_limits_time_window_pair;
+
+-- Drop columns
+ALTER TABLE limits DROP COLUMN IF EXISTS custom_end_date;
+ALTER TABLE limits DROP COLUMN IF EXISTS custom_start_date;
+ALTER TABLE limits DROP COLUMN IF EXISTS active_time_end;
+ALTER TABLE limits DROP COLUMN IF EXISTS active_time_start;

migrations/000007_add_limit_period_columns.up.sql

@@ -0,0 +1,60 @@
+-- ============================================
+-- Migration: 000007_add_limit_period_columns
+-- Description: Add time window and custom period columns to limits table
+-- Date: 2026-03-10
+-- ============================================
+
+-- Add time window columns for daily time-of-day restrictions
+-- Format: "HH:MM" stored as VARCHAR(5) to preserve the exact format
+ALTER TABLE limits ADD COLUMN IF NOT EXISTS active_time_start VARCHAR(5);
+ALTER TABLE limits ADD COLUMN IF NOT EXISTS active_time_end VARCHAR(5);
+
+-- Add custom period columns for CUSTOM limit type
+ALTER TABLE limits ADD COLUMN IF NOT EXISTS custom_start_date TIMESTAMP WITH TIME ZONE;
+ALTER TABLE limits ADD COLUMN IF NOT EXISTS custom_end_date TIMESTAMP WITH TIME ZONE;
+
+-- Add constraint: time window must have both or neither
+ALTER TABLE limits ADD CONSTRAINT chk_limits_time_window_pair
+    CHECK (
+        (active_time_start IS NULL AND active_time_end IS NULL) OR
+        (active_time_start IS NOT NULL AND active_time_end IS NOT NULL)
+    );
+
+-- Add constraint: CUSTOM type requires custom dates
+ALTER TABLE limits ADD CONSTRAINT chk_limits_custom_dates_required
+    CHECK (
+        limit_type != 'CUSTOM' OR 
+        (custom_start_date IS NOT NULL AND custom_end_date IS NOT NULL)
+    );
+
+-- Add constraint: non-CUSTOM types must not have custom dates
+ALTER TABLE limits ADD CONSTRAINT chk_limits_custom_dates_forbidden
+    CHECK (
+        limit_type = 'CUSTOM' OR 
+        (custom_start_date IS NULL AND custom_end_date IS NULL)
+    );
+
+-- Add constraint: custom_start_date must be before custom_end_date
+ALTER TABLE limits ADD CONSTRAINT chk_limits_custom_dates_order
+    CHECK (
+        custom_start_date IS NULL OR custom_end_date IS NULL OR
+        custom_start_date < custom_end_date
+    );
+
+-- Add constraint: time window format validation (HH:MM pattern)
+ALTER TABLE limits ADD CONSTRAINT chk_limits_time_format_start
+    CHECK (
+        active_time_start IS NULL OR
+        active_time_start ~ '^([01][0-9]|2[0-3]):[0-5][0-9]$'
+    );
+
+ALTER TABLE limits ADD CONSTRAINT chk_limits_time_format_end
+    CHECK (
+        active_time_end IS NULL OR
+        active_time_end ~ '^([01][0-9]|2[0-3]):[0-5][0-9]$'
+    );
+
+-- Index for custom period queries (finding limits active during a date range)
+CREATE INDEX IF NOT EXISTS idx_limits_custom_period 
+    ON limits(custom_start_date, custom_end_date) 
+    WHERE limit_type = 'CUSTOM' AND status = 'ACTIVE';

migrations/000008_add_counter_expires_at.down.sql

@@ -0,0 +1,11 @@
+-- ============================================
+-- Migration: 000008_add_counter_expires_at (DOWN)
+-- Description: Remove expires_at column from usage_counters
+-- Date: 2026-03-10
+-- ============================================
+
+-- Drop index first
+DROP INDEX IF EXISTS idx_usage_counters_expires_at;
+
+-- Drop column
+ALTER TABLE usage_counters DROP COLUMN IF EXISTS expires_at;

migrations/000008_add_counter_expires_at.up.sql

@@ -0,0 +1,15 @@
+-- ============================================
+-- Migration: 000008_add_counter_expires_at
+-- Description: Add expires_at column to usage_counters for efficient cleanup
+-- Date: 2026-03-10
+-- ============================================
+
+-- Add expires_at column to store when the counter should be cleaned up
+-- This enables efficient batch cleanup of expired counters
+ALTER TABLE usage_counters ADD COLUMN IF NOT EXISTS expires_at TIMESTAMP WITH TIME ZONE;
+
+-- Index for cleanup queries (finding expired counters)
+-- Partial index only includes rows that have an expiration set
+CREATE INDEX IF NOT EXISTS idx_usage_counters_expires_at 
+    ON usage_counters(expires_at) 
+    WHERE expires_at IS NOT NULL;

pkg/clock/clock.go

@@ -33,3 +33,26 @@ func (RealClock) NewTicker(d time.Duration) (<-chan time.Time, func()) {
 func New() Clock {
 	return RealClock{}
 }
+
+// FixedClock implements Clock with a fixed time. Used for MOCK_TIME support.
+type FixedClock struct {
+	fixedTime time.Time
+}
+
+// Now returns the fixed time.
+func (c FixedClock) Now() time.Time {
+	return c.fixedTime
+}
+
+// NewTicker returns a channel that never fires (fixed clock has no real ticks).
+// Stop is a no-op, matching time.Ticker.Stop() which does not close its channel.
+func (c FixedClock) NewTicker(_ time.Duration) (<-chan time.Time, func()) {
+	ch := make(chan time.Time)
+
+	return ch, func() {}
+}
+
+// NewFixedClock creates a FixedClock that always returns the given time.
+func NewFixedClock(t time.Time) Clock {
+	return FixedClock{fixedTime: t}
+}

pkg/constant/errors.go

@@ -194,6 +194,21 @@ var (
 	// =============================================================================
 	ErrRuleCacheWarmUpFailed = errors.New("TRC-0280") // rule cache warm-up failed
 	ErrRuleCacheNotReady     = errors.New("TRC-0281") // rule cache is not ready
+
+	// =============================================================================
+	// Limit Extended Errors - Time Window & Custom Period (TRC-0300 to TRC-0319)
+	// =============================================================================
+	ErrLimitTimeWindowMismatch       = errors.New("TRC-0300") // activeTimeStart and activeTimeEnd must both be set or both be nil
+	ErrLimitTimeWindowZeroWidth      = errors.New("TRC-0301") // activeTimeStart cannot equal activeTimeEnd
+	ErrTimeOfDayInvalidFormat        = errors.New("TRC-0302") // invalid time of day format, expected HH:MM
+	ErrLimitCustomDatesRequired      = errors.New("TRC-0303") // customStartDate and customEndDate required for CUSTOM limitType
+	ErrLimitCustomDatesOrder         = errors.New("TRC-0304") // customStartDate must be before customEndDate
+	ErrLimitCustomDatesNotAllowed    = errors.New("TRC-0305") // customStartDate/customEndDate only allowed for CUSTOM limitType
+	ErrLimitUnknownType              = errors.New("TRC-0306") // unknown limit type
+	ErrLimitCustomPeriodTooLong      = errors.New("TRC-0307") // custom period cannot exceed 5 years
+	ErrLimitCustomPeriodExpired      = errors.New("TRC-0308") // custom period end date must be in the future
+	ErrLimitInvalidCustomStartFormat = errors.New("TRC-0309") // invalid customStartDate format, expected RFC3339
+	ErrLimitInvalidCustomEndFormat   = errors.New("TRC-0310") // invalid customEndDate format, expected RFC3339
 )
 
 // Error code constants for HTTP responses.

pkg/constant/errors_limit_extended_test.go

@@ -0,0 +1,194 @@
+// Copyright (c) 2026 Lerian Studio. All rights reserved.
+// Use of this source code is governed by the Elastic License 2.0
+// that can be found in the LICENSE file.
+
+package constant
+
+import (
+	"errors"
+	"fmt"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+)
+
+// TestErrorConstants_LimitExtended tests that the new limit-related error constants exist.
+// These are required for WEEKLY, CUSTOM limit types and time window validation.
+func TestErrorConstants_LimitExtended(t *testing.T) {
+	tests := []struct {
+		name     string
+		err      error
+		code     string
+		category string
+	}{
+		{
+			name:     "ErrLimitTimeWindowMismatch exists with code TRC-0300",
+			err:      ErrLimitTimeWindowMismatch,
+			code:     "TRC-0300",
+			category: "time window validation",
+		},
+		{
+			name:     "ErrLimitTimeWindowZeroWidth exists with code TRC-0301",
+			err:      ErrLimitTimeWindowZeroWidth,
+			code:     "TRC-0301",
+			category: "time window validation",
+		},
+		{
+			name:     "ErrTimeOfDayInvalidFormat exists with code TRC-0302",
+			err:      ErrTimeOfDayInvalidFormat,
+			code:     "TRC-0302",
+			category: "time of day parsing",
+		},
+		{
+			name:     "ErrLimitCustomDatesRequired exists with code TRC-0303",
+			err:      ErrLimitCustomDatesRequired,
+			code:     "TRC-0303",
+			category: "custom period validation",
+		},
+		{
+			name:     "ErrLimitCustomDatesOrder exists with code TRC-0304",
+			err:      ErrLimitCustomDatesOrder,
+			code:     "TRC-0304",
+			category: "custom period validation",
+		},
+		{
+			name:     "ErrLimitCustomDatesNotAllowed exists with code TRC-0305",
+			err:      ErrLimitCustomDatesNotAllowed,
+			code:     "TRC-0305",
+			category: "custom period validation",
+		},
+		{
+			name:     "ErrLimitUnknownType exists with code TRC-0306",
+			err:      ErrLimitUnknownType,
+			code:     "TRC-0306",
+			category: "limit type validation",
+		},
+		{
+			name:     "ErrLimitCustomPeriodTooLong exists with code TRC-0307",
+			err:      ErrLimitCustomPeriodTooLong,
+			code:     "TRC-0307",
+			category: "custom period validation",
+		},
+		{
+			name:     "ErrLimitCustomPeriodExpired exists with code TRC-0308",
+			err:      ErrLimitCustomPeriodExpired,
+			code:     "TRC-0308",
+			category: "custom period validation",
+		},
+		{
+			name:     "ErrLimitInvalidCustomStartFormat exists with code TRC-0309",
+			err:      ErrLimitInvalidCustomStartFormat,
+			code:     "TRC-0309",
+			category: "custom period validation",
+		},
+		{
+			name:     "ErrLimitInvalidCustomEndFormat exists with code TRC-0310",
+			err:      ErrLimitInvalidCustomEndFormat,
+			code:     "TRC-0310",
+			category: "custom period validation",
+		},
+	}
+
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			// Verify error is not nil
+			assert.NotNil(t, tc.err, "error constant should exist")
+
+			// Verify error message contains the expected code
+			assert.Contains(t, tc.err.Error(), tc.code,
+				"error message should contain code %s for %s", tc.code, tc.category)
+
+			// Verify it's a proper error type
+			wrapped := fmt.Errorf("wrapped: %w", tc.err)
+			assert.True(t, errors.Is(wrapped, tc.err),
+				"error should be unwrappable with errors.Is")
+		})
+	}
+}
+
+// TestErrorConstants_UniquenessTRC0300Range tests that error codes in TRC-0300 range are unique.
+func TestErrorConstants_UniquenessTRC0300Range(t *testing.T) {
+	// All TRC-0300 range errors that should be unique
+	errorConstants := []error{
+		ErrLimitTimeWindowMismatch,       // TRC-0300
+		ErrLimitTimeWindowZeroWidth,      // TRC-0301
+		ErrTimeOfDayInvalidFormat,        // TRC-0302
+		ErrLimitCustomDatesRequired,      // TRC-0303
+		ErrLimitCustomDatesOrder,         // TRC-0304
+		ErrLimitCustomDatesNotAllowed,    // TRC-0305
+		ErrLimitUnknownType,              // TRC-0306
+		ErrLimitCustomPeriodTooLong,      // TRC-0307
+		ErrLimitCustomPeriodExpired,      // TRC-0308
+		ErrLimitInvalidCustomStartFormat, // TRC-0309
+		ErrLimitInvalidCustomEndFormat,   // TRC-0310
+	}
+
+	// Check for duplicates using error messages
+	seen := make(map[string]int)
+	for i, err := range errorConstants {
+		msg := err.Error()
+		if prev, exists := seen[msg]; exists {
+			t.Errorf("duplicate error code: index %d and %d both have message %q", prev, i, msg)
+		}
+		seen[msg] = i
+	}
+}
+
+// TestErrorConstants_NonEmptyMessages tests that error constants have non-empty error text.
+func TestErrorConstants_NonEmptyMessages(t *testing.T) {
+	tests := []struct {
+		name string
+		err  error
+	}{
+		{
+			name: "time window mismatch has non-empty message",
+			err:  ErrLimitTimeWindowMismatch,
+		},
+		{
+			name: "zero width window has non-empty message",
+			err:  ErrLimitTimeWindowZeroWidth,
+		},
+		{
+			name: "custom dates required has non-empty message",
+			err:  ErrLimitCustomDatesRequired,
+		},
+		{
+			name: "custom dates order has non-empty message",
+			err:  ErrLimitCustomDatesOrder,
+		},
+		{
+			name: "custom dates not allowed has non-empty message",
+			err:  ErrLimitCustomDatesNotAllowed,
+		},
+		{
+			name: "custom period too long has non-empty message",
+			err:  ErrLimitCustomPeriodTooLong,
+		},
+		{
+			name: "invalid time of day format has non-empty message",
+			err:  ErrTimeOfDayInvalidFormat,
+		},
+		{
+			name: "unknown limit type has non-empty message",
+			err:  ErrLimitUnknownType,
+		},
+		{
+			name: "custom period expired has non-empty message",
+			err:  ErrLimitCustomPeriodExpired,
+		},
+		{
+			name: "invalid custom start format has non-empty message",
+			err:  ErrLimitInvalidCustomStartFormat,
+		},
+		{
+			name: "invalid custom end format has non-empty message",
+			err:  ErrLimitInvalidCustomEndFormat,
+		},
+	}
+
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			assert.NotEmpty(t, tc.err.Error(), "error should have a non-empty message")
+		})
+	}
+}