Add filesize DSL and matcher offset for file protocol

[Mzack9999]

Exposes filesize on file protocol events for DSL, and adds optional offset on word/binary/regex matchers so patterns can be pinned to a byte index (e.g. MZ at 0).

Closes #3340

Summary by CodeRabbit

• New Features

  • Added optional offset-based matching for word, binary, and regular-expression matchers.
  • Added file size information, in bytes, to file-processing results.
  • Added support for matching files based on their recorded size.

• Bug Fixes

  • Invalid negative matcher offsets are now rejected during validation.
  • Improved consistency of offset-aware matching across matcher types.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: c0ba2ebb-99e6-4fa7-aa69-224e4766d3f6

📥 Commits

Reviewing files that changed from the base of the PR and between 6d81cc3 and dc29347.

📒 Files selected for processing (9)

• pkg/operators/matchers/match.go
• pkg/operators/matchers/match_test.go
• pkg/operators/matchers/matchers.go
• pkg/operators/matchers/validate.go
• pkg/protocols/file/file.go
• pkg/protocols/file/operators.go
• pkg/protocols/file/operators_test.go
• pkg/protocols/file/request.go
• pkg/protocols/file/request_test.go

---

Walkthrough

The change adds optional offset-pinned matching for words, binary data, and regexes. File protocol events now include total file size in DSL context, with validation and tests covering both features.

Changes

Matcher and file context enhancements

Layer / File(s)	Summary
Offset contract and validation pkg/operators/matchers/matchers.go, pkg/operators/matchers/validate.go	Matcher.Offset is supported for word, binary, and regex matchers, with negative offsets rejected.
Offset-aware matcher evaluation pkg/operators/matchers/match.go, pkg/operators/matchers/match_test.go	Word, binary, and regex matching enforce configured offsets while preserving existing regex paths; offset behavior is tested.
File-size DSL context pkg/protocols/file/file.go, pkg/protocols/file/operators.go, pkg/protocols/file/request.go, pkg/protocols/file/*_test.go	File size is passed through event construction and exposed as filesize in DSL maps, with updated and new tests.

Estimated code review effort: 3 (Moderate) | ~25 minutes

Sequence Diagram(s)

sequenceDiagram
  participant processReader
  participant buildEvent
  participant responseToDSLMap
  processReader->>buildEvent: pass totalBytes
  buildEvent->>responseToDSLMap: pass fileSize
  responseToDSLMap-->>buildEvent: InternalEvent with filesize

Loading

Suggested reviewers: dwisiswant0

Poem

A rabbit hops where offsets gleam,
Regexes anchor like a dream.
Files reveal their byte-sized lore,
DSL maps now count one field more.
“Hop, hop!” the matcher sings,
While filesize joins the strings.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly summarizes the main change: file-protocol filesize DSL support and offset-aware matcher behavior.
Linked Issues check	✅ Passed	The PR covers the linked file-protocol goals for filesize DSL exposure, offset-based matching, and regex handling.
Out of Scope Changes check	✅ Passed	The changes stay focused on file-protocol event data and matcher logic, with no obvious unrelated additions.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch 3340-file-filesize

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}