proxy: introduce per-path request rate limiter

This commit introduces basic configurable rate
limits per pathregex.

Author: hieblmi

README.md

@@ -50,3 +50,52 @@ services and APIs.
   compare with `sample-conf.yaml`.
 * Start aperture without any command line parameters (`./aperture`), all configuration
   is done in the `~/.aperture/aperture.yaml` file.
+
+## Per-endpoint rate limiting
+
+Aperture supports per-endpoint rate limiting using a token bucket based on golang.org/x/time/rate.
+Limits are configured per service using regular expressions that match request paths.
+
+Key properties:
+- Scope: per service, per endpoint (path regex).
+- Process local: state is in-memory per Aperture process. In clustered deployments, each instance enforces its own limits.
+- Evaluation: all matching rules are enforced; if any matching rule denies a request, the request is rejected.
+- Protocols: applies to both REST and gRPC requests.
+
+Behavior on limit exceed:
+- HTTP/REST: returns 429 Too Many Requests and sets a Retry-After header (in seconds). Sub-second delays are rounded up to 1 second.
+- gRPC: response uses HTTP/2 headers/trailers with Grpc-Status and Grpc-Message indicating the error (message: "rate limit exceeded").
+- CORS headers are included consistently.
+
+Configuration fields (under a service):
+- pathregex: regular expression matched against the URL path (e.g., "/package.Service/Method").
+- requests: allowed number of requests per window.
+- per: size of the time window (e.g., 1s, 1m). Default: 1s.
+- burst: additional burst capacity. Default: equal to requests.
+
+Example (see sample-conf.yaml for a full example):
+
+```yaml
+services:
+  - name: "service1"
+    hostregexp: '^service1.com$'
+    pathregexp: '^/.*$'
+    address: "127.0.0.1:10009"
+    protocol: https
+
+    # Optional per-endpoint rate limits using a token bucket.
+    ratelimits:
+      - pathregex: '^/looprpc.SwapServer/LoopOutTerms.*$'
+        requests: 5
+        per: 1s
+        burst: 5
+      - pathregex: '^/looprpc.SwapServer/LoopOutQuote.*$'
+        requests: 2
+        per: 1s
+        burst: 2
+```
+
+Notes:
+- If multiple ratelimits match a request path, all must allow the request; the strictest rule will effectively apply.
+- If requests or burst are set to 0 or negative, safe defaults are used (requests defaults to 1; burst defaults to requests).
+- If per is omitted or 0, it defaults to 1s.

proxy/proxy.go

@@ -10,6 +10,7 @@ import (
 	"os"
 	"strconv"
 	"strings"
+	"time"
 
 	"github.com/lightninglabs/aperture/auth"
 	"github.com/lightninglabs/aperture/l402"
@@ -167,10 +168,47 @@ func (p *Proxy) ServeHTTP(w http.ResponseWriter, r *http.Request) {
 		return
 	}
 
+	// Apply per-endpoint rate limits, if configured.
+	for _, rl := range target.compiledRateLimits {
+		if !rl.re.MatchString(r.URL.Path) {
+			continue
+		}
+
+		// Fast path: allow if a token is available now.
+		if rl.allow() {
+			continue
+		}
+
+		// Otherwise, compute suggested retry delay without consuming
+		// tokens.
+		res := rl.limiter.Reserve()
+		if res.OK() {
+			delay := res.Delay()
+			res.CancelAt(time.Now())
+			if delay > 0 {
+				// As seconds; for sub-second delays we still
+				// send 1 second.
+				secs := int(delay.Seconds())
+				if secs == 0 {
+					secs = 1
+				}
+				w.Header().Set(
+					"Retry-After", strconv.Itoa(secs),
+				)
+			}
+		}
+		addCorsHeaders(w.Header())
+		sendDirectResponse(
+			w, r, http.StatusTooManyRequests, "rate limit exceeded",
+		)
+
+		return
+	}
+
 	resourceName := target.ResourceName(r.URL.Path)
 
-	// Determine auth level required to access service and dispatch request
-	// accordingly.
+	// Determine the auth level required to access service and dispatch the
+	// request  accordingly.
 	authLevel := target.AuthRequired(r)
 	skipInvoiceCreation := target.SkipInvoiceCreation(r)
 	switch {

proxy/ratelimiter.go

@@ -0,0 +1,69 @@
+package proxy
+
+import (
+	"regexp"
+	"time"
+
+	"golang.org/x/time/rate"
+)
+
+// RateLimit defines a per-endpoint rate limit using a token bucket.
+// Requests allowed per time window with optional burst.
+// Example YAML:
+//
+//	ratelimits:
+//	  - pathregex: '^/looprpc.SwapServer/LoopOutQuote.*$'
+//	    requests: 5
+//	    per: 1s
+//	    burst: 5
+//
+// If burst is 0, it defaults to requests.
+// If per is 0, it defaults to 1s.
+// Note: All limits are in-memory and per-process.
+type RateLimit struct {
+	PathRegexp string        `long:"pathregex" description:"Regular expression to match the path of the URL against for rate limiting" yaml:"pathregex"`
+	Requests   int           `long:"requests" description:"Number of requests allowed per time window" yaml:"requests"`
+	Per        time.Duration `long:"per" description:"Size of the time window (e.g., 1s, 1m)" yaml:"per"`
+	Burst      int           `long:"burst" description:"Burst size allowed in addition to steady rate" yaml:"burst"`
+
+	// compiled is internal state prepared at startup.
+	compiled *compiledRateLimit
+}
+
+type compiledRateLimit struct {
+	re      *regexp.Regexp
+	limiter *rate.Limiter
+}
+
+// compile prepares the regular expression and the limiter.
+func (r *RateLimit) compile() error {
+	per := r.Per
+	if per == 0 {
+		per = time.Second
+	}
+	requests := r.Requests
+	if requests <= 0 {
+		requests = 1
+	}
+	burst := r.Burst
+	if burst <= 0 {
+		burst = requests
+	}
+
+	re, err := regexp.Compile(r.PathRegexp)
+	if err != nil {
+		return err
+	}
+
+	// rate.Every(per/requests) creates an average rate of requests
+	// per 'per'.
+	lim := rate.NewLimiter(rate.Every(per/time.Duration(requests)), burst)
+	r.compiled = &compiledRateLimit{re: re, limiter: lim}
+
+	return nil
+}
+
+// allow returns true if the rate limit permits an event now.
+func (c *compiledRateLimit) allow() bool {
+	return c.limiter.Allow()
+}

proxy/service.go

@@ -123,6 +123,12 @@ type Service struct {
 	// invoice creation paths.
 	compiledAuthSkipInvoiceCreationPaths []*regexp.Regexp
 
+	// RateLimits configures per-endpoint rate limits for this service.
+	RateLimits []RateLimit `long:"ratelimits" description:"Per-endpoint rate limits" yaml:"ratelimits"`
+
+	// compiledRateLimits holds compiled regexes and limiter instances.
+	compiledRateLimits []*compiledRateLimit
+
 	freebieDB freebie.DB
 	pricer    pricer.Pricer
 }
@@ -236,6 +242,22 @@ func prepareServices(services []*Service) error {
 			service.compiledPathRegexp = compiledPathRegexp
 		}
 
+		// Compile rate limiters.
+		service.compiledRateLimits = make(
+			[]*compiledRateLimit, 0, len(service.RateLimits),
+		)
+		for i := range service.RateLimits {
+			rl := &service.RateLimits[i]
+			if err := rl.compile(); err != nil {
+				return fmt.Errorf("error compiling rate "+
+					"limit for path %s: %w",
+					rl.PathRegexp, err)
+			}
+			service.compiledRateLimits = append(
+				service.compiledRateLimits, rl.compiled,
+			)
+		}
+
 		service.compiledAuthWhitelistPaths = make(
 			[]*regexp.Regexp, 0, len(service.AuthWhitelistPaths),
 		)