feat(tcp): add structured error codes to protocol responses#46
Merged
pocky merged 1 commit intoMay 11, 2026
Merged
Conversation
- `.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
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
ERRORresponses 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 texterror_codeanderror_messagefields to theResponsedomain type, enabling the TCP server to emit<req_id> ERROR <code> <message>lines while remaining backward-compatible with clients that only match theERRORprefixQueryHandlerto return typed errors for not-found entities (GET,REMOVE,REMOVERULE) and storage failures (SET,RULE SET) instead of collapsing all failures to a booleanChanges
Domain
src/domain/query.zig: AddErrorCodeenum with six variants; extendResponsestruct with optionalerror_codeanderror_messagefields; add domain-level unit tests verifying tag names match wire protocolApplication
src/application/query_handler.zig: ReturnErrorCode.not_foundwith message for missing entities inget,remove,remove_rule; returnErrorCode.internalon storage failure inset,rule_set; update unit tests to assert error code and message valuessrc/application/scheduler.zig: Adddefercleanup forerror_messagein failing-GET test to prevent memory leakInfrastructure
src/infrastructure/tcp_server.zig: Replace bareERROR\nwith code-bearing variants inhandle_connection(auth paths) andwrite_response; expandinvalid_argsdetection toGET,SET,REMOVE,REMOVERULE,RULE SETwith per-command reason strings; add unit tests forwrite_responsewith code-only and code+message responses; minor cleanup offilledvariable in AWF runner builderTests
src/functional_tests.zig: Update existing tests assertingERROR\norreq-1 ERROR\nto 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 examplesdocs/reference/types.md: DocumentErrorCodeenum and updatedResponsestruct fields with usage tabledocs/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 failuresConfig / CI
.awf/config.yaml: Bump version tov0.3.0; addagentsandskillsinputs.awf/workflows/release.yaml: Addupdate_awf_configstep to keep.awf/config.yamlversion in sync during releases; include it in the release commitCLAUDE.md: Remove two stale common-pitfall entries; add two new entries about final-diff analysis and branch scope disciplineTest plan
zig build test-domain— verifyErrorCodetag-name andResponsedefault-field tests passzig build test-application— verifyquery_handlertests coveringnot_found,internal, and null error fields all passzig build test-infrastructure— verify updatedwrite_responseunit tests andhandle_connectionauth tests passzig build test-functional— confirm F023 end-to-end tests pass and existing F011/auth tests still pass with new error stringsCloses #45
Generated with awf commit workflow