Files
ARTEX/traffic/rewrite/trace.go
T
BaaRai 7c74366a44 feat(traffic): add the rewrite-rule engine as a pure package
traffic/rewrite holds the rule model of the capture proxy's rewrite rules,
their save-time validation, an immutable compiled snapshot and the
transformation of one request or response. It imports the standard library
only, so both server and traffic can use it.

Rules run by priority ascending then id ascending, as a pipeline; within a
rule the actions run in a fixed order. A rule is atomic and fails open: a
failing action or a panic cancels that rule only. A rule that needs a body it
cannot touch (binary, over 1 MiB, compressed, streamed, absent by protocol)
is skipped whole. The engine never writes to the URL, headers or bodies it is
given.

Apply returns the trace lines of the phase: the rule snapshot once per rule,
the body of the last body action only, and no value for a sensitive action or
for a field one wrote earlier in the phase. A sensitive value is fingerprinted
with HMAC-SHA256 truncated to 128 bits, or not at all without a key.

Nothing calls the engine from the proxy yet.
2026-11-17 00:12:09 +01:00

107 lines
3.4 KiB
Go

package rewrite
import (
"crypto/hmac"
"crypto/sha256"
"encoding/hex"
"encoding/json"
)
// Outcomes of a trace line.
const (
OutcomeApplied = "applied"
OutcomeSkipped = "skipped"
OutcomeError = "error"
)
// Reasons of a skipped line.
const (
ReasonStream = "not rewritten: stream"
ReasonBinary = "not rewritten: binary"
ReasonBodyTooLarge = "not rewritten: body too large"
ReasonContentEncoding = "not rewritten: content-encoding"
ReasonNoBodyAllowed = "not rewritten: no body allowed"
ReasonConnectionHeader = "header named in Connection"
)
// Error classes: the only thing the engine reports about a failed rule. They
// are the Reason of an error line and the Class of a LastError.
const (
ErrClassInvalidURL = "invalid_url" // a rewritten path and query is not a valid request URI
ErrClassExpansion = "expansion_limit" // a replace result exceeds MaxExpansion
ErrClassPanic = "panic"
)
// TraceLine is one row of an exchange's rewrite trace, in order. An exchange is
// rewritten when it has at least one applied line.
type TraceLine struct {
Phase Phase
RuleID int64 // 0 on a global line
// RuleSnapshot is the rule as JSON, on its first line in the exchange only:
// matchers in clear, sensitive action values left out, longer values summarized.
RuleSnapshot string
Action string
Field string // "method", "url", "header:<Name>", "body" or "status"
Outcome string
Reason string
// BeforeHash and AfterHash are SHA-256 in hex. Once a sensitive action wrote
// the field they are the keyed fingerprint instead, or empty without a key.
BeforeHash string
AfterHash string
// After is the new value. It is nil for a sensitive action, for a field a
// sensitive action wrote earlier in the phase, and for every body line but
// the last one of the phase.
After []byte
}
func sha256Hex(b []byte) string {
sum := sha256.Sum256(b)
return hex.EncodeToString(sum[:])
}
// fingerprint is HMAC-SHA256 truncated to 128 bits. It is not comparable
// between instances, and there is no unkeyed fallback.
func (s *Set) fingerprint(b []byte) string {
if len(s.traceKey) == 0 {
return ""
}
m := hmac.New(sha256.New, s.traceKey)
m.Write(b)
return hex.EncodeToString(m.Sum(nil)[:16])
}
type snapshotAction struct {
Type string `json:"type"`
Name string `json:"name,omitempty"`
Regex string `json:"regex,omitempty"`
Value *string `json:"value,omitempty"`
Sensitive bool `json:"sensitive,omitempty"`
ValueLen int `json:"value_len,omitempty"`
ValueSHA256 string `json:"value_sha256,omitempty"`
}
func ruleSnapshot(r Rule) string {
actions := make([]snapshotAction, 0, len(r.Actions))
for _, a := range r.Actions {
sa := snapshotAction{Type: a.Type, Name: a.Name, Regex: a.Regex, Sensitive: a.Sensitive}
switch {
case a.Sensitive:
case len(a.Value) > snapshotValueMax:
sa.ValueLen, sa.ValueSHA256 = len(a.Value), sha256Hex([]byte(a.Value))
default:
v := a.Value
sa.Value = &v
}
actions = append(actions, sa)
}
out, _ := json.Marshal(struct {
ID int64 `json:"id"`
Name string `json:"name"`
Phase Phase `json:"phase"`
Priority int `json:"priority"`
Matchers Matchers `json:"matchers"`
Actions []snapshotAction `json:"actions"`
}{r.ID, r.Name, r.Phase, r.Priority, r.Matchers, actions})
return string(out)
}