Rate limit

server.RateLimitConfig define request limitation rules. Each rule selects traffic by means of a method and a pattern, and can apply several limits with different identities and strategies.

The project generated by gox createproject includes app/ratelimit.gox with Enabled: false in the main configuration. To activate the limitation, change that value to true. The rules and limits retain their own indicators EnabledThe following example shows an activated configuration.

gox

module ratelimit

import (
    time "time"
    server "github.com/gox-lang/gox/server"
)

var Config = server.RateLimitConfig{
    Enabled: true,
    Rules: []server.RateLimitRule{
        {
            Name:    "login",
            Enabled: true,
            Methods: []string{"POST"},
            Match:   "/actions/login",
            Limits: []server.RateLimitLimit{
                {
                    Name:    "login-by-ip",
                    Enabled: true,
                    By: []server.RateLimitFilter{
                        server.RateLimitFilterIP,
                    },
                    Strategy: server.RateLimitSlidingWindow{
                        Limit:  10,
                        Window: time.Minute,
                    },
                },
            },
        },
        {
            Name:    "api",
            Enabled: true,
            Methods: []string{
                "GET",
                "POST",
            },
            Match:   "/api/*",
            Limits: []server.RateLimitLimit{
                {
                    Name:    "api-by-session",
                    Enabled: true,
                    By: []server.RateLimitFilter{
                        server.RateLimitFilterSession,
                        server.RateLimitFilterRoute,
                    },
                    Strategy: server.RateLimitTokenBucket{
                        Every:  time.Second,
                        Refill: 5,
                        Burst:  20,
                    },
                },
            },
        },
    },
}

Rules

RateLimitRule contains Name, Enabled, Methods, Match and Limits.

Methods empty matches all methods.
server.RateLimitAll It also represents all methods.
Match: "*" It matches any route.
Pattern exists only for compatibility; use Match in new code.

Match uses the same pattern compiler described in Routes. Therefore, it accepts exact routes, parameters, optional segments, alternatives and wildcard with or without extension.

gox

Rules: []server.RateLimitRule{
    {
        Name:    "image-uploads",
        Enabled: true,
        Methods: []string{"POST"},
        Match:   "/(photos|images)/*.(jpg|jpeg|png|webp)",
        Limits: []server.RateLimitLimit{
            {
                Name:    "uploads-by-session",
                Enabled: true,
                By: []server.RateLimitFilter{
                    server.RateLimitFilterSession,
                },
                Strategy: server.RateLimitFixedWindow{
                    Limit:  20,
                    Window: time.Hour,
                },
            },
        },
    },
},

The coincidence is not limited to the visible URL. GOX compares Match with the available route values: the original URL, the current path, the pattern that produced the coincidence and the internal destination. This allows a rule to match before or after a rewriting of Routes.

The rules are evaluated in the declared order and the first one that matches the method and some of those values is used. Match: "*".

`Match`	Scope
`/actions/login`	An exact route.
`/users/:id`	A dynamic segment.
`/reports/:?year`	`/reports` Or a year.
`/(photos\|images)/*`	Both prefixes and any depth.
`/downloads/*.zip`	ZIP files, even within subdirectories.
`*`	All the routes.

Filters

RateLimitLimit.By determines how the identity of the accountant is built.

Filter	Identity
`RateLimitFilterIP`	IP address solved.
`RateLimitFilterSession`	Current session.
`RateLimitFilterRoute`	A coincident route.
`RateLimitFilterMethod`	HTTP method.
`RateLimitFilterURL`	URL requested.

Yeah. By is empty, GOX combines session, IP, route and method. The IP used depends on the configuration of HTTP and their reliable proxies; the sessions are set up in Sessions.

Strategies

Fixed window

gox

Strategy: server.RateLimitFixedWindow{
    Limit:  100,
    Window: time.Minute,
},

Allows up Limit requests inside fixed windows.

Sliding window

gox

Strategy: server.RateLimitSlidingWindow{
    Limit:  30,
    Window: time.Minute,
},

It accounts for requests made during the immediately preceding period.

Token Bucket

gox

Strategy: server.RateLimitTokenBucket{
    Every:  time.Second,
    Refill: 5,
    Burst:  20,
},

Recipe Refill tokens each Every and allows to accumulate up to Burst.

Leaky Bucket

gox

Strategy: server.RateLimitLeakyBucket{
    Every:    time.Second,
    Drain:    5,
    Capacity: 20,
},

Accept until Capacity pending requests and drains Drain each Every.

Hot reload

Enabled, Rules, filters, patterns and strategies are rewarded during hot relay. Subsequent requests immediately use the new policy. The meters belong to the runtime and should not be considered persistent configuration.

If a rule is invalid, GOX retains the previous valid configuration.

Best practices

It uses strict limits for authentication, password recovery and expensive operations.
Assign stable names to rules and limits.
Place specific rules before general rules.
Combine IP and session when a single identity is not enough.
Do not depend exclusively on an IP when there is a shared proxy.
Try each pattern before you deploy it.

Next step

Continue with Sessions to configure their duration and events.

Sessions