Skip to content

feat(tcp): add structured error codes to protocol responses#46

Merged
pocky merged 1 commit into
mainfrom
feature/F023-add-error-messages-to-tcp-protocol-error
May 11, 2026
Merged

feat(tcp): add structured error codes to protocol responses#46
pocky merged 1 commit into
mainfrom
feature/F023-add-error-messages-to-tcp-protocol-error

Conversation

@pocky
Copy link
Copy Markdown
Contributor

@pocky pocky commented May 11, 2026

Summary

  • Replace bare ERROR responses with structured error codes (not_found, invalid_args, auth_required, auth_failed, auth_denied, internal) so clients can distinguish failure reasons without parsing human-readable text
  • Add optional error_code and error_message fields to the Response domain type, enabling the TCP server to emit <req_id> ERROR <code> <message> lines while remaining backward-compatible with clients that only match the ERROR prefix
  • Extend QueryHandler to return typed errors for not-found entities (GET, REMOVE, REMOVERULE) and storage failures (SET, RULE SET) instead of collapsing all failures to a boolean
  • Update protocol and authentication documentation, and add functional tests covering all six error codes end-to-end

Changes

Domain

  • src/domain/query.zig: Add ErrorCode enum with six variants; extend Response struct with optional error_code and error_message fields; add domain-level unit tests verifying tag names match wire protocol

Application

  • src/application/query_handler.zig: Return ErrorCode.not_found with message for missing entities in get, remove, remove_rule; return ErrorCode.internal on storage failure in set, rule_set; update unit tests to assert error code and message values
  • src/application/scheduler.zig: Add defer cleanup for error_message in failing-GET test to prevent memory leak

Infrastructure

  • src/infrastructure/tcp_server.zig: Replace bare ERROR\n with code-bearing variants in handle_connection (auth paths) and write_response; expand invalid_args detection to GET, SET, REMOVE, REMOVERULE, RULE SET with per-command reason strings; add unit tests for write_response with code-only and code+message responses; minor cleanup of filled variable in AWF runner builder

Tests

  • src/functional_tests.zig: Update existing tests asserting ERROR\n or req-1 ERROR\n to the new structured forms; add nine F023 end-to-end tests covering all error codes over live TCP connections; add two F022 concurrent-connection tests (mixed TCP+HTTP, graceful drain)

Documentation

  • docs/reference/protocol.md: Document six error codes with triggering conditions, wire format, and per-command response tables; update all examples
  • docs/reference/types.md: Document ErrorCode enum and updated Response struct fields with usage table
  • docs/user-guide/authentication.md: Replace generic "ERROR" troubleshooting sections with per-code sections (auth_required, auth_failed, auth_denied); add silent-close section for timeouts and TLS failures

Config / CI

  • .awf/config.yaml: Bump version to v0.3.0; add agents and skills inputs
  • .awf/workflows/release.yaml: Add update_awf_config step to keep .awf/config.yaml version in sync during releases; include it in the release commit
  • CLAUDE.md: Remove two stale common-pitfall entries; add two new entries about final-diff analysis and branch scope discipline

Test plan

  • Run zig build test-domain — verify ErrorCode tag-name and Response default-field tests pass
  • Run zig build test-application — verify query_handler tests covering not_found, internal, and null error fields all pass
  • Run zig build test-infrastructure — verify updated write_response unit tests and handle_connection auth tests pass
  • Run zig build test-functional — confirm F023 end-to-end tests pass and existing F011/auth tests still pass with new error strings

Closes #45


Generated with awf commit workflow

- `.awf/config.yaml`: bump version to v0.3.0 and add agent/skill inputs
- `.awf/workflows/release.yaml`: add update_awf_config step to sync version on non-patch releases
- `CLAUDE.md`: replace stale pitfalls with branch-scoping and verification rules
- `docs/reference/protocol.md`: document ErrorCode enum, error response format, and per-command error examples
- `docs/reference/types.md`: add ErrorCode enum and expand Response struct with error_code/error_message fields
- `docs/user-guide/authentication.md`: update troubleshooting sections to use specific auth_required/auth_failed/auth_denied codes
- `src/domain/query.zig`: introduce ErrorCode enum and error_code/error_message fields on Response
- `src/application/query_handler.zig`: return typed ErrorCode on not_found and internal failures; add unit tests
- `src/application/scheduler.zig`: defer-free error_message in missing-job test
- `src/functional_tests.zig`: update assertions to expect specific error codes; add F023 end-to-end tests
- `src/infrastructure/tcp_server.zig`: emit structured ERROR <code> [message] wire responses for all failure paths

Closes #45
@pocky pocky marked this pull request as ready for review May 11, 2026 17:03
@pocky pocky merged commit d58694d into main May 11, 2026
6 checks passed
@pocky pocky deleted the feature/F023-add-error-messages-to-tcp-protocol-error branch May 13, 2026 16:59
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

F023: Add Error Messages to TCP Protocol ERROR Responses

1 participant