Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions changelog.d/changed-crux-lanes-config-errors.md
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
- `crux/lanes` configuration validation now names the failing field and its allowed range, and duration fields accept strings such as `"30s"` or `"5m"` in addition to integer nanoseconds (#16387).
96 changes: 86 additions & 10 deletions src/crux/lanes/config.go
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,8 @@
package lanes

import (
"bytes"
"encoding/json"
"errors"
"fmt"
"net/url"
Expand Down Expand Up @@ -148,16 +150,8 @@ func (c Config) Validate() error {
if err != nil || (u.Scheme != "nats" && u.Scheme != "tls") || u.Host == "" || u.User != nil || u.RawQuery != "" || u.Fragment != "" {
return fmt.Errorf("%w: broker URL must be nats:// or tls:// without inline credentials", ErrInvalid)
}
if !ValidID(c.Namespace) || c.Retention < MinRetention || c.Retention > MaxRetention ||
c.Dedup < MinDedup || c.Dedup > c.Retention || c.Lease < MinLease || c.Lease > MaxLease ||
c.AckRetention < c.Lease || c.AckRetention > c.Retention || c.Timeout <= 0 || c.Timeout > MaxTimeout ||
c.RetryDelay < MinRetryDelay || c.MaxRetryDelay < c.RetryDelay || c.MaxRetryDelay > MaxRetryDelay ||
c.MaxPayload <= 0 || c.MaxPayload > MaxPayload || c.MaxMessages <= 0 || c.MaxMessages > MaxLaneMessages ||
c.MaxBytes < int64(c.MaxPayload) || c.MaxBytes > MaxStorageBytes || c.MaxKVBytes <= 0 || c.MaxKVBytes > MaxStorageBytes ||
c.MaxPending <= 0 || c.MaxLedger < c.MaxPending || c.MaxLedger > MaxLedgerEntries ||
c.Replicas < 1 || c.Replicas > MaxReplicas || len(c.Lanes) > DefaultMaxLanes ||
len(c.Principals) == 0 || len(c.Principals) > DefaultMaxMembers {
return fmt.Errorf("%w: lane configuration bounds", ErrInvalid)
if err := c.validateBounds(); err != nil {
return err
}
if c.CredentialsEnv != "" && !validEnv(c.CredentialsEnv) {
return fmt.Errorf("%w: broker credential binding", ErrInvalid)
Expand Down Expand Up @@ -273,3 +267,85 @@ func (b *Broker) Registry(project string) []api.Lane {
}
return out
}

func bound(field string, bad bool, rng string, got any) error {
if !bad {
return nil
}
return fmt.Errorf("%w: lanes: %s must be %s, got %v", ErrInvalid, field, rng, got)
}

func (c Config) validateBounds() error {
checks := []error{
bound("namespace", !ValidID(c.Namespace), fmt.Sprintf("a lowercase identifier of at most %d characters", MaxIDLength), fmt.Sprintf("%q", c.Namespace)),
bound("retention", c.Retention < MinRetention || c.Retention > MaxRetention, fmt.Sprintf("between %s and %s", MinRetention, MaxRetention), c.Retention),
bound("dedup", c.Dedup < MinDedup || c.Dedup > c.Retention, fmt.Sprintf("between %s and retention (%s)", MinDedup, c.Retention), c.Dedup),
bound("lease", c.Lease < MinLease || c.Lease > MaxLease, fmt.Sprintf("between %s and %s", MinLease, MaxLease), c.Lease),
bound("ack_retention", c.AckRetention < c.Lease || c.AckRetention > c.Retention, fmt.Sprintf("between lease (%s) and retention (%s)", c.Lease, c.Retention), c.AckRetention),
bound("timeout", c.Timeout <= 0 || c.Timeout > MaxTimeout, fmt.Sprintf("greater than 0 and at most %s", MaxTimeout), c.Timeout),
bound("retry_delay", c.RetryDelay < MinRetryDelay, fmt.Sprintf("at least %s", MinRetryDelay), c.RetryDelay),
bound("max_retry_delay", c.MaxRetryDelay < c.RetryDelay || c.MaxRetryDelay > MaxRetryDelay, fmt.Sprintf("between retry_delay (%s) and %s", c.RetryDelay, MaxRetryDelay), c.MaxRetryDelay),
bound("max_payload", c.MaxPayload <= 0 || c.MaxPayload > MaxPayload, fmt.Sprintf("between 1 and %d", MaxPayload), c.MaxPayload),
bound("max_messages", c.MaxMessages <= 0 || c.MaxMessages > MaxLaneMessages, fmt.Sprintf("between 1 and %d", MaxLaneMessages), c.MaxMessages),
bound("max_bytes", c.MaxBytes < int64(c.MaxPayload) || c.MaxBytes > MaxStorageBytes, fmt.Sprintf("between max_payload (%d) and %d", c.MaxPayload, MaxStorageBytes), c.MaxBytes),
bound("max_kv_bytes", c.MaxKVBytes <= 0 || c.MaxKVBytes > MaxStorageBytes, fmt.Sprintf("between 1 and %d", MaxStorageBytes), c.MaxKVBytes),
bound("max_pending", c.MaxPending <= 0, "at least 1", c.MaxPending),
bound("max_ledger", c.MaxLedger < c.MaxPending || c.MaxLedger > MaxLedgerEntries, fmt.Sprintf("between max_pending (%d) and %d", c.MaxPending, MaxLedgerEntries), c.MaxLedger),
bound("replicas", c.Replicas < 1 || c.Replicas > MaxReplicas, fmt.Sprintf("between 1 and %d", MaxReplicas), c.Replicas),
bound("lanes", len(c.Lanes) > DefaultMaxLanes, fmt.Sprintf("at most %d entries", DefaultMaxLanes), len(c.Lanes)),
bound("principals", len(c.Principals) == 0 || len(c.Principals) > DefaultMaxMembers, fmt.Sprintf("between 1 and %d entries", DefaultMaxMembers), len(c.Principals)),
}
for _, err := range checks {
if err != nil {
return err
}
}
return nil
}

// flexDuration accepts a JSON number (nanoseconds) or a time.ParseDuration string.
type flexDuration time.Duration

func (d *flexDuration) UnmarshalJSON(data []byte) error {
var s string
if json.Unmarshal(data, &s) == nil {
v, err := time.ParseDuration(s)
if err != nil {
return fmt.Errorf("invalid duration %q: %w", s, err)
}
*d = flexDuration(v)
return nil
}
var n int64
if err := json.Unmarshal(data, &n); err != nil {
return fmt.Errorf("duration must be a string such as \"30s\" or integer nanoseconds")
}
*d = flexDuration(n)
return nil
}

// UnmarshalJSON accepts duration fields as integer nanoseconds or strings such as "30s".
// It decodes strictly: the outer decoder's DisallowUnknownFields does not propagate
// into Unmarshaler methods, so unknown keys must be rejected here.
func (c *Config) UnmarshalJSON(data []byte) error {
type plain Config
aux := struct {
*plain
Retention flexDuration `json:"retention"`
Dedup flexDuration `json:"dedup"`
Lease flexDuration `json:"lease"`
AckRetention flexDuration `json:"ack_retention"`
RetryDelay flexDuration `json:"retry_delay"`
MaxRetryDelay flexDuration `json:"max_retry_delay"`
Timeout flexDuration `json:"timeout"`
}{plain: (*plain)(c)}
d := json.NewDecoder(bytes.NewReader(data))
d.DisallowUnknownFields()
if err := d.Decode(&aux); err != nil {
return err
}
c.Retention, c.Dedup, c.Lease = time.Duration(aux.Retention), time.Duration(aux.Dedup), time.Duration(aux.Lease)
c.AckRetention, c.RetryDelay = time.Duration(aux.AckRetention), time.Duration(aux.RetryDelay)
c.MaxRetryDelay, c.Timeout = time.Duration(aux.MaxRetryDelay), time.Duration(aux.Timeout)
return nil
}
70 changes: 70 additions & 0 deletions src/crux/lanes/config_duration_test.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,70 @@
package lanes

import (
"encoding/json"
"errors"
"strings"
"testing"
"time"
)

func TestConfigDurationsAcceptStringsAndNanoseconds(t *testing.T) {
var c Config
if err := json.Unmarshal([]byte(`{"lease":"30s","timeout":5000000000,"retention":"5m","namespace":"x","max_payload":10}`), &c); err != nil {
t.Fatal(err)
}
if c.Lease != 30*time.Second || c.Timeout != 5*time.Second || c.Retention != 5*time.Minute || c.Namespace != "x" || c.MaxPayload != 10 {
t.Fatalf("unexpected config: %+v", c)
}
if err := json.Unmarshal([]byte(`{"lease":"bogus"}`), &c); err == nil {
t.Fatal("expected error for invalid duration")
}
}

func TestConfigUnmarshalRejectsUnknownFields(t *testing.T) {
valid := `{"url":"nats://localhost:4222","lease":"30s","principals":[{"project":"atlas","token_env":"ATLAS_TOKEN"}]}`
var c Config
if err := json.Unmarshal([]byte(valid), &c); err != nil {
t.Fatal(err)
}
for _, test := range []struct {
name string
body string
}{
{"unknown top-level", `{"url":"nats://localhost:4222","leese":"30s","principals":[{"project":"atlas","token_env":"ATLAS_TOKEN"}]}`},
{"unknown nested", `{"url":"nats://localhost:4222","principals":[{"project":"atlas","token_env":"ATLAS_TOKEN","token":"dummy"}]}`},
} {
t.Run(test.name, func(t *testing.T) {
var c Config
err := json.Unmarshal([]byte(test.body), &c)
if err == nil || !strings.Contains(err.Error(), "unknown field") {
t.Fatalf("expected unknown field error, got %v", err)
}
_, err = loadConfig(strings.NewReader(test.body))
if !errors.Is(err, ErrInvalid) || !strings.Contains(err.Error(), "unknown field") {
t.Fatalf("expected loadConfig unknown field error, got %v", err)
}
})
}
}

func TestLoadConfigSurfacesDurationError(t *testing.T) {
body := `{"url":"nats://localhost:4222","lease":"bogus","principals":[{"project":"atlas","token_env":"ATLAS_TOKEN"}]}`
_, err := loadConfig(strings.NewReader(body))
if !errors.Is(err, ErrInvalid) || !strings.Contains(err.Error(), `invalid duration "bogus"`) {
t.Fatalf("expected invalid duration error, got %v", err)
}
}

func TestValidateNamesFailingField(t *testing.T) {
c := Config{URL: "nats://localhost:4222", Principals: []Principal{{Project: "atlas", TokenEnv: "ATLAS_TOKEN"}}}
c.Defaults()
if err := c.Validate(); err != nil {
t.Fatal(err)
}
c.MaxPending = -1
err := c.Validate()
if !errors.Is(err, ErrInvalid) || !strings.Contains(err.Error(), "max_pending") {
t.Fatalf("expected max_pending error, got %v", err)
}
}
2 changes: 1 addition & 1 deletion src/crux/lanes/load.go
Original file line number Diff line number Diff line change
Expand Up @@ -32,7 +32,7 @@ func loadConfig(r io.Reader) (Config, error) {
d.DisallowUnknownFields()
var cfg Config
if err := d.Decode(&cfg); err != nil {
return Config{}, fmt.Errorf("%w: cannot decode lane configuration", ErrInvalid)
return Config{}, fmt.Errorf("%w: cannot decode lane configuration: %v", ErrInvalid, err)
}
var extra any
if err := d.Decode(&extra); err != io.EOF {
Expand Down
7 changes: 5 additions & 2 deletions src/docs/crux-lanes.md
Original file line number Diff line number Diff line change
Expand Up @@ -240,8 +240,11 @@ but remain in the bounded ledger and are never silently ACKed or discarded.

## Bounds and failure behavior

Configuration uses integer nanoseconds for duration fields; omitted or zero
values select defaults. Negative/invalid explicit values fail initialization.
Duration fields accept either a string parsed by Go `time.ParseDuration`
(for example `"30s"` or `"5m"`) or an integer number of nanoseconds; omitted or
zero values select defaults. Out-of-range settings fail validation with an
error naming the field and its allowed range, for example
`lanes: max_pending must be at least 1, got -1`. Negative/invalid explicit values fail initialization.
Short retention remains supported even when an operation timeout is longer:
expiry produces explicit generation/cursor errors, not a false duplicate ACK.
For normal deployments choose retention comfortably above polling, retry and
Expand Down
Loading