Configuration files

The config package loads resource-scoped policies from JSON or YAML into core.ResourceConfig. It does not load the simpler core.Config shape.

Canonical YAML

examples/configuration_file/limits.yaml

gorl:
  strategy: sliding_window
  fail_open: false
  default:
    limit: 100
    window: 1m
  resources:
    login:
      limit: 5
      window: 1m
    search:
      limit: 50
      window: 1s

The same fields can be expressed as JSON. Both formats accept either the namespaced gorl object shown above or a flat object containing strategy, default, and resources directly.

Load and run

examples/configuration_file/main.go

// Package main demonstrates loading resource-scoped limits from a YAML or JSON file.
package main

import (
    "context"
    "flag"
    "fmt"
    "log"

    "github.com/AliRizaAynaci/gorl/v2"
    "github.com/AliRizaAynaci/gorl/v2/config"
)

func main() {
    configPath := flag.String("config", "examples/configuration_file/limits.yaml", "path to a GoRL YAML or JSON config")
    flag.Parse()

    cfg, err := config.LoadResourceConfig(*configPath)
    if err != nil {
        log.Fatalf("load config: %v", err)
    }

    limiter, err := gorl.NewResourceLimiter(cfg)
    if err != nil {
        log.Fatalf("create limiter: %v", err)
    }
    defer limiter.Close()

    result, err := limiter.AllowResource(context.Background(), "login", "user-123")
    if err != nil {
        log.Fatalf("evaluate limit: %v", err)
    }

    fmt.Printf("allowed=%v limit=%d remaining=%d\n", result.Allowed, result.Limit, result.Remaining)
}

Run it from the repository root:

go run ./examples/configuration_file \
  -config examples/configuration_file/limits.yaml

Expected first decision:

allowed=true limit=5 remaining=4

Schema

Field	Required	Meaning
strategy	Yes	fixed_window, sliding_window, token_bucket, or leaky_bucket
redis_url	No	Selects the bundled Redis backend when non-empty
fail_open	No	Defaults to false
default.limit	Yes	Positive fallback capacity
default.window	Yes	Positive Go duration string
resources	No	Map of resource name to policy override

Windows use Go duration syntax such as 250ms, 30s, 1m, or 2h. A bare number such as 60 is invalid.

Validation and errors

Loading fails when:

• the extension is not .json, .yaml, or .yml,
• the file cannot be read,
• JSON or YAML is malformed,
• a duration cannot be parsed,
• a limit or window is not positive,
• a resource name is empty.

An unknown strategy is detected later by gorl.NewResourceLimiter, after the configuration document has been converted and validated.

Configuration is loaded once

LoadResourceConfig does not watch the file. To reload policies, the application must load a new config, construct a replacement limiter, route new traffic to it, and close the old limiter after in-flight work drains.

Production handling

• Treat configuration as startup input and fail deployment early on invalid policy.
• Do not log Redis credentials embedded in redis_url.
• Review the default policy as carefully as named overrides because unknown resources silently use it.
• Keep configuration examples in tests or executable examples so field names cannot drift unnoticed.