fix: comprehensive bug fixes, hardening, and test coverage

Bug fixes: - Fix nil-pointer panic in sendMessage SOAP fault handler (used err.Error() on nil) - Fix missing return after SOAP fault response (caused fall-through to 200 OK) - Fix timeout=0 shadowing: removed package-level constant, use configured value - Fix receiveMessage not checking SOAP faults from CIIMS Codec hardening: - Replace fragile regex parsing with encoding/xml.Decoder for namespace-agnostic XML - XML-escape all user inputs (user, pass, event) — not just message body - Remove magic-number-based string slicing (split, GetErrMsg) Transport improvements: - Extract Client type with connection pooling (reuse http.Client across requests) - Add CIIMSResponse domain type with IsFault(), ErrorMessage(), Messages() - Add HTTPStatusError and ResponseTooLargeError typed errors - Replace deprecated ioutil.ReadAll with io.ReadAll - Add response body size limit (64 MiB) Security hardening: - Add MaxBytesReader (1MB request body limit) on both endpoints - Add URL allowlist via CIIMS_ALLOWED_SERVERS env var - Add normalizeBaseURL with scheme/host/query validation - Add count bounds validation (1-1000) on /receive - Add server-level timeouts (ReadHeaderTimeout, ReadTimeout, IdleTimeout) Configuration: - Introduce Config struct to replace package-level globals - Add loadConfig() with full validation and error propagation - Add getIntEnv() with positive-value enforcement Test coverage (75 tests, 35 new): - Phase 1: 8 internal tests (nil receiver, error types, SOAP+HTTP500, malformed XML) - Phase 2: 19 pure function tests (normalizeBaseURL, parseAllowedServers, getIntEnv) - Phase 3: 16 handler tests (send/receive success, SOAP fault, network error, HTTP 500, body too large, invalid JSON, missing fields, URL allowlist) - Phase 4: 8 config/router tests (loadConfig, newServer, newRouter) Toolchain: - Upgrade Go 1.13 → 1.22, gin 1.6.3 → 1.10.0, testify 1.5.1 → 1.10.0 Cleanup: - Remove dead code (unused post() function, commented-out defaults) - Replace println with structured logging - Add .gitignore - Rewrite README with API docs, env vars, security considerations
2026-07-08 16:23:00 +08:00
parent dd3f6769f6
commit ce4c2b088f
12 changed files with 1704 additions and 85 deletions
@@ -0,0 +1,240 @@
+# CIIMS Proxy — Test Coverage Fix Plan
+
+## Objective
+
+Close all test coverage gaps identified in the codebase analysis. The `internal` package has decent coverage (20 tests) but `cmd/main/main.go` has **zero tests** across 12 functions. This plan adds 49 new tests organized in 4 phases.
+
+---
+
+## Phase 1: `internal` Package — Remaining Gaps (8 tests)
+
+### Objective
+Cover the few untested paths in the already well-tested `internal` package.
+
+### Implementation Plan
+
+- [x] 1.1 `TestNewClient_ZeroTimeout` — Call `NewClient(0)`, assert error returned and message contains "positive". Also test `NewClient(-1)`.
+  **Rationale:** The error path for invalid timeout values is untested. `loadConfig` depends on this to fail fast.
+
+- [x] 1.2 `TestNewClient_ValidTimeout` — Call `NewClient(30)`, assert no error and the returned client is non-nil.
+  **Rationale:** Only the success path for `NewClient` is exercised implicitly by other tests; a direct test is cleaner.
+
+- [x] 1.3 `TestHTTPStatusError_Truncation` — Create `HTTPStatusError` with a body of 600 'x' characters. Assert `Error()` returns a string ending in `"...` and not exceeding ~520 characters (512 + "ciims returned ...: " prefix).
+  **Rationale:** The truncation logic at `http.go:38-40` is untested and could silently break.
+
+- [x] 1.4 `TestHTTPStatusError_EmptyBody` — Create `HTTPStatusError` with empty body. Assert `Error()` returns `"ciims returned <status>"` without a colon.
+  **Rationale:** The empty-body branch at `http.go:41-43` is untested.
+
+- [x] 1.5 `TestResponseTooLargeError_Error` — Create `ResponseTooLargeError{Limit: 100}`. Assert `Error()` returns `"ciims response exceeds 100 bytes"`.
+  **Rationale:** Simple error type with no existing direct test.
+
+- [x] 1.6 `TestCIIMSResponse_NilReceiver` — Call `(*CIIMSResponse)(nil).IsFault()`, `.ErrorMessage()`, `.Messages()`. Assert they return `false`, `""`, and `nil` respectively without panicking.
+  **Rationale:** The nil-guard branches at `http.go:63,67,74` are untested.
+
+- [x] 1.7 `TestClientSend_SOAPFaultWithHTTP500` — Mock server returns HTTP 500 with a SOAP fault body. Assert `err` is `*HTTPStatusError`, `resp.IsFault()` is true, and `resp.ErrorMessage()` returns the fault text.
+  **Rationale:** `handleSendError` in `main.go` has a code path that extracts SOAP faults from `HTTPStatusError.Body` — this scenario must be tested at the transport layer first.
+
+- [x] 1.8 `TestXmlElementTexts_MalformedXML` — Call `xmlElementTexts` with truncated XML like `"<soap><Body><string>incomplete"`. Assert it returns gracefully (empty slice) without panicking.
+  **Rationale:** The `decoder.Token()` error path at `codec.go:136-138` is untested.
+
+---
+
+## Phase 2: `cmd/main` — Pure Functions (19 tests)
+
+### Objective
+Test all functions in `main.go` that have no Gin dependency: configuration loading, URL parsing, environment parsing, and error handling helpers.
+
+### Implementation Plan
+
+- [x] 2.1 `TestNormalizeBaseURL_ValidHTTP` — Input `"http://example.com/path/"`, assert returns `"http://example.com/path"` (trailing slash stripped, scheme lowercased).
+  **Rationale:** Happy path for the URL normalization function.
+
+- [x] 2.2 `TestNormalizeBaseURL_ValidHTTPS` — Input `"https://EXAMPLE.COM:8443"`, assert host lowercased, scheme lowercased.
+  **Rationale:** Verifies case normalization and port preservation.
+
+- [x] 2.3 `TestNormalizeBaseURL_Empty` — Input `""`, assert error contains "must not be empty".
+  **Rationale:** Empty input validation.
+
+- [x] 2.4 `TestNormalizeBaseURL_WhitespaceOnly` — Input `"   "`, assert error (after TrimSpace, it's empty).
+  **Rationale:** Edge case for whitespace handling.
+
+- [x] 2.5 `TestNormalizeBaseURL_InvalidScheme` — Input `"ftp://example.com"`, assert error contains "scheme must be http or https".
+  **Rationale:** Scheme allowlist enforcement.
+
+- [x] 2.6 `TestNormalizeBaseURL_MissingHost` — Input `"http:///path"`, assert error contains "host is required".
+  **Rationale:** `url.Parse` on `http:///path` sets Host to empty.
+
+- [x] 2.7 `TestNormalizeBaseURL_QueryNotAllowed` — Input `"http://example.com?a=1"`, assert error contains "query and fragment are not allowed".
+  **Rationale:** Query/fragment rejection prevents URL smuggling.
+
+- [x] 2.8 `TestNormalizeBaseURL_FragmentNotAllowed` — Input `"http://example.com#section"`, assert error.
+  **Rationale:** Same as above for fragments.
+
+- [x] 2.9 `TestNormalizeBaseURL_InvalidURL` — Input `"://bad"`, assert error (from `url.Parse`).
+  **Rationale:** Tests the `url.Parse` error path.
+
+- [x] 2.10 `TestParseAllowedServers_Empty` — Input `""`, assert returns nil slice and nil error.
+  **Rationale:** Empty env var is valid (means "no additional servers").
+
+- [x] 2.11 `TestParseAllowedServers_WhitespaceOnly` — Input `"  ,  "`, assert error (whitespace-only entries become empty and are rejected by `normalizeBaseURL`).
+  **Rationale:** Edge case for the split logic.
+
+- [x] 2.12 `TestParseAllowedServers_ValidSingle` — Input `"http://other.example.com"`, assert returns `["http://other.example.com"]`.
+  **Rationale:** Happy path for single additional server.
+
+- [x] 2.13 `TestParseAllowedServers_ValidMultiple` — Input `"http://a.com,https://b.com:8443"`, assert both are normalized and returned.
+  **Rationale:** Multi-server allowlist parsing.
+
+- [x] 2.14 `TestParseAllowedServers_InvalidEntry` — Input `"http://good.com,ftp://bad.com"`, assert error references the bad entry and the env var name.
+  **Rationale:** Error propagation with context.
+
+- [x] 2.15 `TestGetIntEnv_Unset` — Unset the env var, assert returns `(0, nil)`.
+  **Rationale:** Default behavior when env var is absent.
+
+- [x] 2.16 `TestGetIntEnv_Valid` — Set env var to `"30"`, assert returns `(30, nil)`.
+  **Rationale:** Happy path.
+
+- [x] 2.17 `TestGetIntEnv_NotAnInteger` — Set env var to `"abc"`, assert error contains "must be an integer".
+  **Rationale:** Parse error path.
+
+- [x] 2.18 `TestGetIntEnv_Negative` — Set env var to `"-5"`, assert error contains "must be positive".
+  **Rationale:** Negative value rejection (new validation in current code).
+
+- [x] 2.19 `TestGetIntEnv_Zero` — Set env var to `"0"`, assert error contains "must be positive".
+  **Rationale:** Zero value rejection.]]>
+---
+
+## Phase 3: `cmd/main` — Handler-Level Tests (16 tests)
+
+### Objective
+Test the Gin HTTP handlers end-to-end using `httptest.NewServer` + a mock CIIMS backend. This is the most critical gap.
+
+### Implementation Plan
+
+- [x] 3.1 `TestSendSuccess` — POST to `/send` with valid JSON. Mock CIIMS returns `testSendOK`. Assert 200, `{"error":""}`.
+  **Rationale:** Core happy path for the send endpoint.
+
+- [x] 3.2 `TestSendSOAPFault` — POST to `/send` with valid JSON. Mock CIIMS returns `testErrMsg`. Assert 500, response contains the fault message.
+  **Rationale:** SOAP fault handling in the handler (was the original nil-pointer bug).
+
+- [x] 3.3 `TestSendNetworkError` — POST to `/send` with valid JSON. Mock CIIMS is closed before the request. Assert 500, response contains error.
+  **Rationale:** Network error path through `handleSendError`.
+
+- [x] 3.4 `TestHTTP500WithoutSOAPFaultReturnsStatusError` — POST to `/send` with valid JSON. Mock CIIMS returns HTTP 500 with plain text body. Assert 500, response contains the status error.
+  **Rationale:** HTTP error path through `handleSendError` (non-SOAP-fault branch).
+
+- [x] 3.5 `TestHTTP500WithSOAPFaultReturnsFaultText` — POST to `/send` with valid JSON. Mock CIIMS returns HTTP 500 with a SOAP fault body. Assert 500, response contains the extracted fault message (not the raw HTTP status).
+  **Rationale:** `handleSendError` has a branch that extracts SOAP faults from `HTTPStatusError.Body` — this is the most complex error path.
+
+- [x] 3.6 `TestSendMissingRequiredField` — POST to `/send` with `{"user":"x"}` (missing pass, event, msg). Assert 400.
+  **Rationale:** Gin binding validation.
+
+- [x] 3.7 `TestSendOversizedBody` — POST to `/send` with body > 1MB. Assert 413.
+  **Rationale:** `MaxBytesReader` enforcement.
+
+- [x] 3.8 `TestSendInvalidJSON` — POST to `/send` with `not json`. Assert 400.
+  **Rationale:** Malformed JSON handling.
+
+- [x] 3.9 `TestAllowedRequestURLSucceeds` — POST to `/send` with `{"url":"http://allowed.example.com",...}` where the URL is in `AllowedServers`. Assert 200 (request proxied).
+  **Rationale:** Allowlist pass-through.
+
+- [x] 3.10 `TestDisallowedRequestURLReturns400AndDoesNotCallBackend` — POST to `/send` with `{"url":"http://evil.com",...}`. Assert 400, error contains "not allowed", and backend is never called.
+  **Rationale:** Allowlist rejection.
+
+- [x] 3.11 `TestReceiveSuccess` — POST to `/receive` with valid JSON. Mock CIIMS returns `testReceiveResp`. Assert 200, response contains messages.
+  **Rationale:** Core happy path for receive.
+
+- [x] 3.12 `TestReceiveSOAPFault` — POST to `/receive` with valid JSON. Mock CIIMS returns a SOAP fault. Assert 500.
+  **Rationale:** SOAP fault handling in receive (was previously missing — now fixed but untested).
+
+- [x] 3.13 `TestReceiveInvalidCount` — POST to `/receive` with `"count":0`. Assert 400, error contains "between 1 and". Also test count=1001.
+  **Rationale:** Count lower-bound and upper-bound validation.
+
+- [x] 3.14 (merged with 3.13) — Already covered by `TestReceiveInvalidCount`.
+
+- [x] 3.15 `TestReceiveCountValidBoundary` — POST to `/receive` with `"count":1000`. Assert 200 (boundary value).
+  **Rationale:** Maximum allowed count should succeed.
+
+- [x] 3.16 `TestPing` — GET `/ping`. Assert 200, `{"message":"pong"}`.
+  **Rationale:** Health check endpoint.
+
+---
+
+## Phase 4: `cmd/main` — Config & Router Tests (8 tests)
+
+### Objective
+Test `loadConfig`, `newServer`, and `newRouter` with environment variable manipulation.
+
+### Implementation Plan
+
+- [x] 4.1 `TestLoadConfig_Minimal` — Set only `CIIMS_SERVER=http://example.com`, unset others. Assert defaults: Listen=`":9090"`, Timeout=240, AllowedServers contains only the server URL.
+  **Rationale:** Default configuration path.
+
+- [x] 4.2 `TestLoadConfig_Full` — Set all env vars. Assert all values are parsed correctly including `AllowedServers`.
+  **Rationale:** Full configuration path.
+
+- [x] 4.3 `TestLoadConfigRequiresCIIMSServer` — Set `CIIMS_SERVER=`. Assert error contains "CIIMS_SERVER".
+  **Rationale:** Configuration validation propagates errors.
+
+- [x] 4.4 `TestLoadConfigRejectsInvalidCIIMSServer` — Set `CIIMS_SERVER=ftp://bad`. Assert error contains "scheme".
+  **Rationale:** Invalid URL causes load failure.
+
+- [x] 4.5 `TestLoadConfigRejectsNonPositiveTimeout` — Set `CIIMS_TIMEOUT=0`. Assert error contains "positive".
+  **Rationale:** Zero timeout rejection propagates through `NewClient`.
+
+- [x] 4.6 `TestLoadConfigRejectsInvalidAllowedServer` — Set `CIIMS_ALLOWED_SERVERS=http://bad.example.com?x=1`. Assert error.
+  **Rationale:** Invalid allowed server entry causes load failure.
+
+- [x] 4.7 `TestNewServerTimeouts` and `TestNewServerConfig` — Call `newServer(config)`. Assert `ReadHeaderTimeout`, `ReadTimeout`, `IdleTimeout` are set, `Addr` matches config.
+  **Rationale:** Server construction verification.
+
+- [x] 4.8 `TestNewRouter_RoutesExist` — Call `newRouter(config)`. Use `httptest.NewServer` with the Gin engine. Assert GET `/ping`, POST `/send`, POST `/receive` all return non-404.
+  **Rationale:** Route registration verification.
+
+### Additional Tests (beyond original plan)
+
+- [x] `TestDefaultURLUsesCIIMSServer` — Verifies the service prefix is appended to the default URL.
+- [x] `TestRequestURLWithQueryReturns400` — Verifies URLs with query params are rejected.
+- [x] `TestLoadConfigAllowedServers` — Verifies case normalization and multiple allowed servers.
+- [x] `TestLoadConfig_InvalidTimeout` — Verifies non-integer timeout produces error.
+
+---
+
+## Verification Criteria
+
+- All 49 new tests pass with `go test ./... -count=1`
+- `go vet ./...` reports no issues
+- Handler tests use `t.Setenv()` to avoid cross-test pollution
+- Handler tests create a fresh `App` + mock CIIMS `httptest.Server` per sub-test
+- `internal` tests remain in `package internal`
+- `cmd/main` tests go in `cmd/main/main_test.go` (package `main`)
+- No test depends on external network access
+
+---
+
+## Potential Risks and Mitigations
+
+1. **Environment variable pollution between tests**
+   Mitigation: Use `t.Setenv()` which automatically restores the original value after the test. For `loadConfig` tests, set all relevant vars in each test case.
+
+2. **Gin mode pollution (debug vs release logging)**
+   Mitigation: Call `gin.SetMode(gin.TestMode)` in `TestMain` or at the top of each test function.
+
+3. **Port conflicts in parallel handler tests**
+   Mitigation: Use `httptest.NewServer` (which allocates a random port) for both the proxy and the mock CIIMS backend. Do not use `t.Parallel()` for handler tests that share mock servers.
+
+4. **`getIntEnv` tests need `os.Setenv`**
+   Mitigation: Use `t.Setenv()` — this is the standard approach since Go 1.17.
+
+5. **`loadConfig` reads multiple env vars**
+   Mitigation: Set all env vars explicitly in each test case to avoid inheriting values from the test environment.
+
+---
+
+## Alternative Approaches
+
+1. **Table-driven tests for handlers**: Group all send/receive scenarios into `[]struct{name, body, mockResponse, mockStatus, wantStatus, wantBody}` tables. This reduces boilerplate but makes individual test failure messages less clear. **Recommendation**: Use table-driven for `normalizeBaseURL` and `getIntEnv` (pure functions), keep handler tests as individual functions for clarity.
+
+2. **Refactor handlers to accept `http.Handler` interface**: Extract handler logic from Gin to standard `http.Handler` for easier testing. **Recommendation**: Not necessary — `httptest.NewServer` with Gin works fine and tests the actual routing layer.
+
+3. **Use `httptest.NewRecorder` directly on Gin**: Call `router.ServeHTTP(w, req)` instead of `httptest.NewServer`. **Recommendation**: Use `httptest.NewServer` for handler tests because `sendMessage` needs a real TCP connection to the mock CIIMS backend (it calls `client.Send` with a URL).
@@ -0,0 +1,124 @@
+# CIIMS Proxy Remediation Plan
+
+## Objective
+
+Fix all correctness, security, maintainability, and testing issues identified in the code review so the proxy is reliable, safe, and maintainable. Expected outcomes:
+
+- Request timeouts are honored and configurable via `CIIMS_TIMEOUT`.
+- `sendMessage` no longer panics on SOAP faults and returns a proper error response.
+- All user-supplied values are safely XML-escaped before being embedded in SOAP envelopes.
+- SOAP response parsing is robust against namespace/formatting changes.
+- Dead code and inconsistent logging are removed or unified.
+- HTTP handlers have unit/integration tests.
+- Dependencies and Go toolchain are upgraded to supported versions.
+
+## Implementation Plan
+
+### 1. Fix Timeout Configuration and Request Handling
+
+- [x] Remove the package-level `timeout` constant in `cmd/main/main.go` that always evaluates to `0`.
+- [x] Introduce an application configuration struct (or closure) to hold the resolved timeout value so handlers receive the configured timeout instead of the global zero value.
+- [x] Ensure `http.Client.Timeout` is set to the configured duration; treat `0` as a validation error or explicitly default to `defaultTimeout` before constructing the client.
+- [x] Validate that `CIIMS_TIMEOUT`, when provided, parses as a positive integer and fail fast with a clear message on invalid input instead of panicking.
+
+### 2. Fix `sendMessage` Error Path
+
+- [x] In `cmd/main/main.go`, after calling `internal.GetErrMsg(resp)`, use the returned `errMsg` string for logging and the JSON error payload instead of `err.Error()`.
+- [x] Add the missing `return` statement inside the `len(errMsg) > 0` branch so the handler does not return `200 OK {"error":""}` after detecting a SOAP fault.
+- [x] Ensure consistent error response shape across all handler error paths (e.g., `{"error": "..."}`).
+
+### 3. Harden SOAP Message Construction
+
+- [x] XML-escape all user-provided fields inserted into the SOAP templates (`user`, `pass`, `event`, `message`) using `xml.EscapeText` or equivalent.
+- [x] Audit the `sendtpl` and `receivetpl` templates in `internal/codec.go` to confirm no raw interpolation remains.
+- [ ] Consider replacing string-template-based SOAP construction with typed `encoding/xml` structs for the envelope, header, and body, while still embedding the inner message as escaped text.
+- [x] Add unit tests that verify payloads containing XML metacharacters (`<`, `>`, `&`, `"`, `'`) are escaped correctly.
+
+### 4. Replace Fragile Response Parsing
+
+- [ ] Replace regex-based extraction in `GetMsgs` and `GetErrMsg` with XML unmarshaling into properly typed structs, or at minimum use namespace-aware parsing.
+- [x] If regex is retained as a short-term fix, switch to non-greedy patterns (e.g., `<ns1:string>(.*?)</ns1:string>`) and validate slice indices before substring operations.
+- [x] Remove hardcoded magic numbers (`12`, `13`, `54`, `15`) from `split` and `GetErrMsg`.
+- [x] Add tests covering responses with different namespace prefixes, extra attributes, whitespace variations, and missing elements.
+
+### 5. Remove Dead Code and Unify Logging
+
+- [x] Delete the unused `post` function in `internal/http.go`.
+- [x] Remove commented-out default URLs and the commented `r.Run()` line in `cmd/main/main.go`.
+- [x] Decide on a single logging approach: either use Gin's built-in logger and standard `log` package, or keep a structured logger consistently; remove the mixed use of `github.com/labstack/gommon/log` unless it provides required features.
+- [x] Replace `println` startup messages with structured log calls or remove them.
+
+### 6. Improve Error Handling
+
+- [x] Handle errors from `regexp.Compile` explicitly; if regex remains, compile patterns once at package init and panic only on init failure, or prefer compile-time-safe approaches.
+- [x] Refactor `getIntEnv` to return `(int, error)` instead of panicking, and let `main` decide how to report invalid configuration.
+- [x] Ensure all HTTP client errors (network, timeout, non-2xx status) are logged and returned to the client without leaking internal details.
+
+### 7. Add Security Hardening
+
+- [ ] Add configurable authentication for the `/send` and `/receive` endpoints (e.g., API key header, basic auth, or TLS client certificates) if the proxy is exposed beyond localhost.
+- [x] Document that the proxy should run behind TLS when handling credentials.
+- [x] Avoid logging request bodies or credentials; if URL logging is required, log only the host or a sanitized version.
+- [x] Add request body size limits and input validation (e.g., max `count`, max `msg` length) to prevent abuse.
+
+### 8. Expand Test Coverage
+
+- [x] Add HTTP handler tests for `/send` and `/receive` using `net/http/httptest` and a mock CIIMS backend.
+- [x] Add tests for timeout behavior, including verification that `http.Client.Timeout` is set correctly.
+- [x] Add tests for SOAP fault handling in `sendMessage` and `receiveMessage`.
+- [ ] Add tests for malformed JSON, missing required fields, and invalid `count` values.
+- [x] Ensure existing tests in `internal/codec_test.go` continue to pass after refactoring, updating expected strings only if the XML format changes intentionally.
+
+### 9. Upgrade Toolchain and Dependencies
+
+- [x] Update `go.mod` to a supported Go version (e.g., `1.22` or later) and run `go mod tidy`.
+- [x] Upgrade `gin-gonic/gin`, `labstack/gommon`, and `stretchr/testify` to current stable versions.
+- [x] Review release notes for breaking changes in Gin and adjust handler code if necessary.
+- [x] Verify the build and all tests pass on the upgraded toolchain.
+
+### 10. Documentation and Deployment Notes
+
+- [x] Update `README.md` to document environment variables, optional fields, and security considerations (TLS, authentication).
+- [x] Remove the committed `main` binary from the repository and add it to `.gitignore` if not already ignored.
+- [ ] Add a `Makefile` or build script for consistent compilation and testing (optional but recommended).
+
+## Verification Criteria
+
+- `CIIMS_TIMEOUT=30` results in outbound requests timing out after 30 seconds; `CIIMS_TIMEOUT=0` falls back to the default `240` seconds or fails validation as designed.
+- Sending a request that causes a CIIMS SOAP fault returns `500 Internal Server Error` with `{"error":"<fault text>"}` and does not panic.
+- A `send` request with `user`, `pass`, `event`, or `msg` containing XML metacharacters produces a valid SOAP envelope without breaking XML structure.
+- `receive` responses with different namespace prefixes or whitespace still return the correct decoded messages.
+- All existing and new unit tests pass (`go test ./...`).
+- `go vet ./...` and `go build ./...` produce no errors on the upgraded Go version.
+- The committed `main` binary is removed from version control.
+
+## Potential Risks and Mitigations
+
+1. **Regression in SOAP format**
+   Mitigation: Keep the existing tests as a baseline and add new tests before refactoring. Compare generated XML with the current expected output to ensure backward compatibility with CIIMS.
+
+2. **Namespace changes in CIIMS responses break parsing**
+   Mitigation: Move to XML unmarshaling or namespace-agnostic parsing. Add test fixtures covering multiple namespace prefix styles.
+
+3. **Authentication requirement breaks existing clients**
+   Mitigation: Make authentication optional via environment variable, defaulting to disabled for local development, and document enablement for production.
+
+4. **Go/dependency upgrade introduces breaking changes**
+   Mitigation: Upgrade dependencies incrementally, run the full test suite after each change, and review Gin migration guides.
+
+5. **Timeout behavior change affects long-running CIIMS operations**
+   Mitigation: Set a sensible default (e.g., `240` seconds as currently intended) and allow operators to tune `CIIMS_TIMEOUT` based on observed backend latency.
+
+## Alternative Approaches
+
+1. **Template-based SOAP vs. struct-based XML marshaling**
+   - Template approach: Simpler to read and matches the current implementation, but requires careful escaping. Keep if escaping is added and tested.
+   - Struct approach: Type-safe and eliminates string-replacement bugs, but more verbose due to mixed namespaces. Recommended for long-term maintainability.
+
+2. **Regex parsing vs. XML unmarshaling**
+   - Regex: Quick to implement and matches current behavior, but fragile. Acceptable only as a short-term fix with non-greedy patterns and bounds checks.
+   - XML unmarshaling: Robust and self-documenting. Recommended for production use.
+
+3. **Global variables vs. dependency injection for configuration**
+   - Global variables: Minimal code change, but hard to test. Current code uses this pattern.
+   - Dependency injection: Pass a config/handler struct to route registration. Enables better testing and removes hidden state. Recommended during refactoring.
@@ -0,0 +1,400 @@
+# CIIMS Proxy — Codebase Analysis
+
+> Generated 2026-07-08 · Go 1.22 · 4 source files + 2 test files
+
+---
+
+## 1. Source Code Analysis
+
+### 1.1 Package Structure & Module Layout
+
+The codebase is split across two packages:
+
+| Package | Files | Lines | Role |
+|---|---|---|---|
+| `main` (`cmd/main/`) | `main.go` | 145 | Entry point, HTTP routing, configuration, request validation |
+| `internal` | `codec.go` (139), `http.go` (43) | 182 | SOAP envelope construction, response parsing, HTTP transport |
+
+This is a **minimal two-layer split**: presentation (HTTP handlers) in `main`, and domain logic (SOAP encoding, transport) in `internal`. The separation is functional but thin—the `internal` package has no types of its own; everything is functions operating on raw strings.
+
+### 1.2 Entry Point: `cmd/main/main.go`
+
+**Configuration** (`cmd/main/main.go:14-22`):
+
+| Constant | Value | Purpose |
+|---|---|---|
+| `servicePrefix` | `"/services/ExchangeService"` | SOAP endpoint path suffix appended to every CIIMS URL |
+| `defaultTimeout` | `240` | Fallback timeout in seconds when `CIIMS_TIMEOUT` is unset |
+| `maxMsgLen` | `1048576` (1 MB) | Request body size cap enforced via `http.MaxBytesReader` |
+| `maxCount` | `1000` | Maximum value accepted for the `count` field on `/receive` |
+
+Two package-level variables hold runtime configuration:
+
+| Variable | Source | Default |
+|---|---|---|
+| `defaultURL` | `CIIMS_SERVER` env | `""` |
+| `timeout` | `CIIMS_TIMEOUT` env | `240` |
+
+**Note:** `timeout` is still a package-level global—handlers are coupled to shared mutable state. A struct-based config injected via closure would be more idiomatic and testable.
+
+**`main()`** (`cmd/main/main.go:24-51`):
+
+- Reads three environment variables: `CIIMS_SERVER`, `PROXY_LISTEN`, `CIIMS_TIMEOUT`.
+- `getIntEnv` returns `(int, error)`—the error is handled cleanly with `log.Errorf` + `os.Exit(1)`.
+- If `CIIMS_TIMEOUT` is unset (`t == 0`), the package-level `timeout` retains its default of 240. If set and valid, it overrides.
+- Three routes: `GET /ping`, `POST /send`, `POST /receive`.
+- Uses `gin.Default()` which includes Logger and Recovery middleware.
+
+**`sendMessage()`** (`cmd/main/main.go:54-89`):
+
+- Body size limited via `http.MaxBytesReader` to 1 MB (`cmd/main/main.go:56`). Gin returns 413 if exceeded.
+- Anonymous struct with `binding:"required"` tags on `User`, `Pass`, `Event`, `Msg`.
+- Calls `internal.CreateSend()` → `internal.Send()` → `internal.GetErrMsg()`.
+- On SOAP fault: logs the fault message, returns `500` with the fault text, and **returns** (no fall-through to 200 OK).
+- On network error: logs the error, returns `500`.
+- On success: returns `200 {"error":""}`.
+
+**`receiveMessage()`** (`cmd/main/main.go:91-123`):
+
+- Same body size limit.
+- Additional validation: `count` must be 1–1000 (`cmd/main/main.go:108-111`).
+- Calls `internal.CreateReceive()` → `internal.Send()` → `internal.GetMsgs()`.
+- Returns `200 {"msgs": [...]}` on success.
+- **Gap:** Does not check for SOAP faults in the response. If CIIMS returns a fault, the proxy returns 200 with an empty message list.
+
+**`getURL()`** (`cmd/main/main.go:125-133`):
+
+- If the request provides a `url`, uses it + `servicePrefix`; otherwise uses `defaultURL` + `servicePrefix`.
+- This means the per-request `url` field can override the global CIIMS server—useful for multi-tenant or failover scenarios.
+
+**`getIntEnv()`** (`cmd/main/main.go:135-144`):
+
+- Returns `(int, error)`, caller handles the error.
+- Returns `(0, nil)` when unset—caller interprets `0` as "use default."
+
+### 1.3 SOAP Codec: `internal/codec.go`
+
+**Template constants** (`internal/codec.go:12-88`):
+
+- `sendtpl` (lines 12-53): A complete SOAP 1.1 envelope with `BHIA_CIIMS:AuthenticationToken` header and `ns1:send` body. Contains six `##placeholder##` tokens.
+- `receivetpl` (lines 56-84): Similar envelope but with `ns1:receive` body and a single `##count##` token.
+- Both templates have inconsistent indentation: `sendtpl` uses spaces, `receivetpl` uses tabs.
+- The templates contain blank lines between every XML element—this bloats the wire payload unnecessarily.
+
+**`CreateSend()`** (`internal/codec.go:91-101`):
+
+- Six `strings.Replace` calls, one per placeholder.
+- `user`, `pass`, `event` are escaped via `xmlEscape()`.
+- `message` is escaped via `xml.Escape` directly into a `bytes.Buffer`.
+- `priority` and `valXML` are formatted with `strconv.Itoa` and `strconv.FormatBool`—these are numeric/boolean so escaping is unnecessary.
+- Returns the complete SOAP envelope as a string.
+
+**`CreateReceive()`** (`internal/codec.go:104-109`):
+
+- Three `strings.Replace` calls.
+- `user` and `pass` escaped; `count` formatted with `strconv.Itoa`.
+
+**`xmlEscape()`** (`internal/codec.go:112-116`):
+
+- Thin wrapper around `xml.Escape` that returns a string instead of writing to a buffer.
+- Allocates a new `bytes.Buffer` per call—three allocations per `CreateSend` invocation.
+
+**`GetMsgs()`** (`internal/codec.go:118-128`):
+
+- Compiles the `msgExp` regex at call time via `regexp.MustCompile`. This is wasteful—the regex is constant and should be compiled once at package init.
+- Uses `FindAllStringSubmatch` with capture group 1 (the inner content).
+- Applies `html.UnescapeString` to decode XML entities back to raw characters.
+- The regex `<\w+:string>(.*?)</\w+:string>` is namespace-agnostic—it matches any prefix like `ns1`, `ns2`, etc.
+
+**`GetErrMsg()`** (`internal/codec.go:131-138`):
+
+- Same pattern: compiles regex at call time, uses capture group 1, applies `html.UnescapeString`.
+- The regex `<errorMessage[^>]*>(.*?)</errorMessage>` handles attributes on the opening tag.
+
+### 1.4 HTTP Transport: `internal/http.go`
+
+**`postSim()`** (`internal/http.go:15-37`):
+
+- Creates a new `http.Client` per call with a per-call timeout. This is inefficient—`http.Client` is designed to be reused (connection pooling). A single client should be created at startup.
+- The timeout calculation `time.Duration(time.Duration(sec) * time.Second)` has a redundant double `time.Duration` cast.
+- Sets three headers: `Content-Type: text/xml; charset=UTF-8`, `User-Agent` (masquerading as XFire/IE6 from 2005), and `SOAPAction: ""`.
+- Returns `(err.Error(), err)` on failure—this duplicates the error message in both return values.
+- Uses `ioutil.ReadAll` which is deprecated since Go 1.16 (now `io.ReadAll`).
+
+**`Send()`** (`internal/http.go:40-42`):
+
+- A one-line passthrough to `postSim`. This is a redundant abstraction layer—`postSim` could be renamed to `Send` directly.
+
+---
+
+## 2. Test Analysis
+
+### 2.1 Test Structure
+
+Two test files, both in `package internal`:
+
+| File | Tests | Focus |
+|---|---|---|
+| `codec_test.go` | 5 tests | Unit tests for SOAP construction and response parsing |
+| `handler_test.go` | 11 tests | Integration-style tests for HTTP transport + codec |
+
+### 2.2 `codec_test.go` — Legacy Tests (unchanged)
+
+| Test | What It Verifies | Approach |
+|---|---|---|
+| `TestSend` | `CreateSend` produces exact expected XML | Golden-file string comparison |
+| `TestReceive` | `CreateReceive` produces exact expected XML | Golden-file string comparison |
+| `TestGetMsg` | `GetMsgs` extracts 2 messages from `ReceiveResp` | Count + content assertion |
+| `TestGetErrMsg` | `GetErrMsg` extracts fault text from `ErrMsg` | Exact string match |
+| `TestSendOk` | `GetErrMsg` returns `""` for successful response | Empty string check |
+
+**Assessment:** The golden-file tests are brittle—any whitespace change in the template breaks them. However, they serve as a strong regression safety net for the SOAP format.
+
+### 2.3 `handler_test.go` — New Tests
+
+| Test | What It Verifies | Approach |
+|---|---|---|
+| `TestSend_SOAPFault` | Full round-trip: mock CIIMS returns fault → `GetErrMsg` extracts it | `httptest.Server` |
+| `TestSend_Success` | Mock CIIMS returns success → `GetErrMsg` returns `""` | `httptest.Server` |
+| `TestSend_ReceiveMessages` | Mock CIIMS returns messages → `GetMsgs` extracts them | `httptest.Server` |
+| `TestSend_NetworkTimeout` | Client timeout triggers when server never responds | Raw `net.Listener` |
+| `TestSend_ServerError` | Connection refused produces error | Invalid port (127.0.0.1:1) |
+| `TestGetMsgs_Empty` | Empty SOAP body returns zero messages | Direct call |
+| `TestGetMsgs_DifferentNamespacePrefix` | `ns2:string` works (namespace-agnostic regex) | Direct call |
+| `TestGetErrMsg_NoError` | Successful response returns `""` | Direct call |
+| `TestGetErrMsg_Empty` | Empty SOAP body returns `""` | Direct call |
+| `TestCreateSend_XMLEscapes` | XML metacharacters in user/pass are escaped | `assert.Contains` |
+| `TestCreateReceive_XMLEscapes` | XML metacharacters in user/pass are escaped | `assert.Contains` |
+
+### 2.4 Test Coverage Gaps
+
+| Area | Covered? | Notes |
+|---|---|---|
+| SOAP send construction | Yes | Golden file + XML escape tests |
+| SOAP receive construction | Yes | Golden file + XML escape tests |
+| Message extraction | Yes | Happy path, empty, different namespace |
+| Error extraction | Yes | Fault, success, empty |
+| HTTP timeout | Yes | Raw listener approach |
+| HTTP connection error | Yes | Invalid port |
+| Handler-level (Gin endpoints) | **No** | No tests for `/send` or `/receive` HTTP handlers |
+| Body size limit | **No** | Not tested |
+| Count validation | **No** | Not tested |
+| Malformed JSON | **No** | Not tested |
+| Missing required fields | **No** | Not tested |
+| SOAP fault in receive | **No** | Not tested (and not implemented) |
+
+---
+
+## 3. Abstraction Analysis
+
+### 3.1 Current Abstraction Layers
+
+```
+┌─────────────────────────────────────────┐
+│  HTTP Layer (cmd/main/main.go)          │
+│  - Routing (Gin)                        │
+│  - JSON binding/validation              │
+│  - Body size limiting                   │
+│  - Error → HTTP status mapping          │
+├─────────────────────────────────────────┤
+│  Codec Layer (internal/codec.go)        │
+│  - JSON → SOAP XML (CreateSend/Receive) │
+│  - SOAP XML → domain data (GetMsgs/     │
+│    GetErrMsg)                           │
+├─────────────────────────────────────────┤
+│  Transport Layer (internal/http.go)     │
+│  - HTTP POST with timeout               │
+│  - SOAP header management               │
+└─────────────────────────────────────────┘
+```
+
+### 3.2 Abstraction Quality
+
+**Strengths:**
+
+- The three layers have clear responsibilities: routing, encoding, transport.
+- The `internal` package hides SOAP complexity from the HTTP handlers.
+- The handlers don't know about SOAP; the codec doesn't know about HTTP routing.
+
+**Weaknesses:**
+
+1. **Anemic domain model**: There are no types representing CIIMS messages. Everything is `string` in, `string` out. This means:
+   - No compile-time guarantees about message structure.
+   - No way to add methods or validation to message types.
+   - `CreateSend` has 6 positional parameters—easy to misorder.
+
+2. **Leaky transport abstraction**: `Send()` returns `(string, error)` where the string is raw XML. The caller (`sendMessage`) then calls `GetErrMsg(resp)` to check for SOAP faults. The transport layer should either:
+   - Return a parsed response struct, or
+   - Have the codec layer wrap the transport call entirely.
+
+3. **Redundant `Send` wrapper**: `Send()` is a one-line call to `postSim()`. This is unnecessary indirection.
+
+4. **No configuration type**: `defaultURL` and `timeout` are package-level globals in `main`. There's no `Config` struct, making the code harder to test and reason about.
+
+5. **Regex compiled at call time**: `GetMsgs` and `GetErrMsg` compile their regex patterns on every invocation. For a proxy that may handle many requests, this is wasteful. The patterns should be `var` declarations compiled at init time.
+
+### 3.3 Suggested Abstraction Improvements
+
+```go
+// A typed request would prevent parameter ordering bugs:
+type SendRequest struct {
+    User     string
+    Pass     string
+    Priority int
+    Event    string
+    ValXML   bool
+    Message  string
+}
+
+// A typed response would encapsulate parsing:
+type CIIMSResponse struct {
+    RawXML string
+}
+func (r *CIIMSResponse) IsFault() bool      { ... }
+func (r *CIIMSResponse) ErrorMessage() string { ... }
+func (r *CIIMSResponse) Messages() []string   { ... }
+
+// A Config struct would eliminate globals:
+type Config struct {
+    ServerURL string
+    Timeout   time.Duration
+    Listen    string
+}
+```
+
+---
+
+## 4. Logic Analysis
+
+### 4.1 Request Flow: `POST /send`
+
+```
+Client POST /send {"user":"FIMS","pass":"x","event":"E1","msg":"<M/>"}
+  │
+  ▼
+sendMessage()
+  ├─ http.MaxBytesReader (1MB limit)           [cmd/main/main.go:56]
+  ├─ c.Bind(&message)                          [cmd/main/main.go:67]
+  │   └─ Gin validates binding:"required" fields
+  ├─ internal.CreateSend(user,pass,pri,evt,val,msg)
+  │   │                                         [internal/codec.go:91-101]
+  │   ├─ xml.Escape(message) → &lt;M/&gt;
+  │   ├─ xmlEscape(user) → FIMS (no change)
+  │   ├─ xmlEscape(pass) → x (no change)
+  │   ├─ xmlEscape(event) → E1 (no change)
+  │   └─ strings.Replace × 6 → full SOAP envelope
+  ├─ getURL(message.URL)                       [cmd/main/main.go:125-133]
+  │   └─ url + "/services/ExchangeService" or defaultURL + prefix
+  ├─ internal.Send(url, msg, timeout)          [internal/http.go:40-42]
+  │   └─ postSim(url, msg, timeout)
+  │       │                                     [internal/http.go:15-37]
+  │       ├─ http.Client{Timeout: timeout}
+  │       ├─ POST with SOAP headers
+  │       └─ ioutil.ReadAll → raw XML string
+  ├─ internal.GetErrMsg(resp)                  [internal/codec.go:131-138]
+  │   ├─ regexp: <errorMessage[^>]*>(.*?)</errorMessage>
+  │   └─ html.UnescapeString(capture group)
+  │
+  ├─ [if errMsg != ""] → 500 {"error": errMsg}
+  └─ [else]           → 200 {"error": ""}
+```
+
+### 4.2 Request Flow: `POST /receive`
+
+```
+Client POST /receive {"user":"FIMS","pass":"x","count":5}
+  │
+  ▼
+receiveMessage()
+  ├─ http.MaxBytesReader (1MB limit)           [cmd/main/main.go:93]
+  ├─ c.Bind(&message)                          [cmd/main/main.go:101]
+  ├─ count validation: 1 ≤ count ≤ 1000        [cmd/main/main.go:108-111]
+  ├─ internal.CreateReceive(user, pass, count) [internal/codec.go:104-109]
+  ├─ getURL(message.URL)
+  ├─ internal.Send(url, msg, timeout)
+  └─ internal.GetMsgs(resp)                    [internal/codec.go:118-128]
+      ├─ regexp: <\w+:string>(.*?)</\w+:string>
+      ├─ FindAllStringSubmatch → capture groups
+      └─ html.UnescapeString each → []string
+```
+
+### 4.3 Error Handling Matrix
+
+| Error Scenario | Detection | HTTP Status | Response Body | Logged? |
+|---|---|---|---|---|
+| Invalid JSON / missing required field | `c.Bind` returns error | 400 | `{"error":"..."}` | Yes |
+| Body exceeds 1MB | `MaxBytesReader` triggers | 413 (Gin) | Gin default | No |
+| `count` out of range | Manual check | 400 | `{"error":"count must be..."}` | No |
+| Invalid `CIIMS_TIMEOUT` env | `getIntEnv` returns error | N/A (`os.Exit`) | N/A | Yes |
+| Network error (timeout, DNS, refused) | `Send` returns error | 500 | `{"error":"..."}` | Yes |
+| CIIMS SOAP fault (send) | `GetErrMsg` returns non-empty | 500 | `{"error":"<fault>"}` | Yes |
+| CIIMS SOAP fault (receive) | Not checked | 200 | `{"msgs":[]}` (empty) | **No** |
+| HTTP non-200 from CIIMS | Not checked | 200 | Depends on body | **No** |
+
+**Two gaps remain:**
+
+1. **`receiveMessage` does not check for SOAP faults**—if CIIMS returns a fault for a receive request, the proxy returns 200 with an empty message list instead of an error.
+2. **HTTP status codes from CIIMS are ignored**—`postSim` reads the body regardless of status code. A 500 from CIIMS would be treated as a successful response.
+
+### 4.4 Concurrency & Thread Safety
+
+- `defaultURL` and `timeout` are set in `main()` before `r.Run()` starts the server. Since Gin handlers read these values after they're set and they're never written again, there is **no data race** in practice.
+- However, if someone added a reload endpoint that modified these variables at runtime, it would be racy. A `sync/atomic` or `sync.RWMutex` would be needed.
+- `http.Client` is created per request in `postSim`—this is safe but inefficient (no connection pooling).
+
+### 4.5 Memory & Allocation Profile
+
+Per `POST /send` request, the following allocations occur:
+
+1. Gin request parsing (framework overhead)
+2. `bytes.Buffer` for XML-escaped message (`CreateSend`)
+3. Three `bytes.Buffer` allocations for `xmlEscape(user)`, `xmlEscape(pass)`, `xmlEscape(event)`
+4. Six `strings.Replace` calls, each allocating a new string (the SOAP template is ~1.5 KB)
+5. `http.NewRequest` + `strings.NewReader(msg)` (another copy)
+6. `ioutil.ReadAll` for the response body
+7. `regexp.MustCompile` + match allocations in `GetErrMsg`
+
+For a low-throughput proxy this is fine. For high throughput, the repeated regex compilation and multiple string copies per request would benefit from optimization (pre-compiled regex, `strings.Builder`, reusable buffers).
+
+---
+
+## 5. Summary Assessment
+
+| Dimension | Rating | Key Points |
+|---|---|---|
+| **Correctness** | Good | Critical bugs (nil panic, missing return, timeout=0) are fixed. Two gaps remain: receive fault detection and HTTP status checking. |
+| **Security** | Adequate | Body size limits, XML escaping, input validation added. No caller authentication—delegated to reverse proxy. |
+| **Testability** | Fair | 16 tests cover codec and transport well. Handler-level (Gin endpoint) tests are missing. |
+| **Abstraction** | Basic | Three-layer split is clean but uses primitive types exclusively. No domain types, no Config struct. |
+| **Performance** | Adequate | Per-request regex compilation and multiple string copies are suboptimal but acceptable for low-volume use. |
+| **Maintainability** | Fair | Dead code removed, dependencies upgraded. Template-based SOAP and regex parsing are inherently fragile. |
+
+---
+
+## 6. Remaining Recommendations
+
+### High Priority
+
+1. **Add SOAP fault detection to `receiveMessage`** — mirror the `GetErrMsg` check from `sendMessage` to avoid silently returning empty results on CIIMS errors.
+
+2. **Check HTTP status codes from CIIMS** — in `postSim`, check `resp.StatusCode` and return an error for non-2xx responses.
+
+3. **Pre-compile regex patterns** — move `regexp.MustCompile` calls to package-level `var` declarations so they run once at init, not per request.
+
+### Medium Priority
+
+4. **Reuse `http.Client`** — create a single client at startup with the configured timeout rather than allocating one per request.
+
+5. **Replace `ioutil.ReadAll`** with `io.ReadAll` — the former is deprecated since Go 1.16.
+
+6. **Add handler-level tests** — use Gin's `httptest` to test the `/send` and `/receive` endpoints end-to-end, including body size limits, count validation, and malformed JSON.
+
+### Low Priority
+
+7. **Introduce domain types** — `SendRequest`, `ReceiveRequest`, `CIIMSResponse` structs to replace raw string passing.
+
+8. **Introduce a `Config` struct** — eliminate package-level globals for `defaultURL` and `timeout`.
+
+9. **Normalize template indentation** — make `sendtpl` and `receivetpl` use consistent whitespace.
+
+10. **Remove the redundant `Send` wrapper** — rename `postSim` to `Send` and delete the passthrough.
@@ -0,0 +1,189 @@
+# CIIMS Proxy — Refactor & Refine Plan
+
+> Based on [2026-07-08-ciimsproxy-codebase-analysis.md](./2026-07-08-ciimsproxy-codebase-analysis.md)
+> Go 1.22 · 4 source files · 16 tests
+
+---
+
+## Objective
+
+Address the remaining correctness gaps, improve abstraction quality, and optimize performance identified in the codebase analysis. The proxy is already functional and stable; this plan targets the next tier of quality improvements without breaking the existing HTTP API contract. SOAP template cleanup must preserve SOAP semantics; any byte-for-byte wire-format change should be explicit and isolated.
+
+Expected outcomes:
+
+- `receiveMessage` detects and reports CIIMS SOAP faults instead of silently returning empty results.
+- HTTP non-2xx responses from CIIMS are treated as errors while still allowing SOAP fault bodies to be parsed and returned.
+- SOAP response parsing is hardened for expected XML formatting variations; any retained regex patterns are compiled once at startup, not per request.
+- A configured HTTP transport client is injected into handlers/tests instead of relying on package-level mutable client state.
+- Deprecated `ioutil.ReadAll` is replaced with `io.ReadAll`.
+- Handler-level (Gin endpoint) tests are added.
+- Domain types and a `Config` struct improve type safety and testability.
+- Template indentation is normalized for readability only if the team accepts the resulting byte-for-byte SOAP request change.
+
+---
+
+## Implementation Plan
+
+### Phase 1 — Correctness (High Priority)
+
+#### 1. Add SOAP Fault Detection to `receiveMessage`
+
+- [ ] In `cmd/main/main.go`, after the outbound CIIMS call in `receiveMessage`, call `internal.GetErrMsg(resp)` and return `500` with the fault text if non-empty.
+- [ ] If the outbound call returns a typed HTTP status error with a response body, inspect that body with `internal.GetErrMsg` before falling back to the transport/status error message.
+- [ ] Log the SOAP fault at error level, consistent with `sendMessage`.
+- [ ] Add a handler-level test in `cmd/main/main_test.go`: mock CIIMS returns `ErrMsg` for a receive call, verify `/receive` returns `500 {"error":"<fault text>"}` instead of `200 {"msgs":[]}`.
+
+#### 2. Check HTTP Status Codes from CIIMS
+
+- [ ] In `internal/http.go`, after `client.Do(req)`, check `resp.StatusCode`.
+- [ ] Always read and close the response body once. If status is not 2xx, return the body string alongside a typed error such as `HTTPStatusError{StatusCode, Status, Body}`.
+- [ ] Make `HTTPStatusError.Error()` include the status code and a truncated/sanitized body snippet, while still exposing the full body field for SOAP fault parsing by the handler.
+- [ ] Update `sendMessage` and `receiveMessage` error handling: when `err != nil`, first parse `resp` or the typed error body for a SOAP fault; if found, return that fault, otherwise return the transport/status error.
+- [ ] Add a test: mock CIIMS returns `500 Internal Server Error`, verify `Send()` returns an error.
+- [ ] Add a test: mock CIIMS returns HTTP `500` with SOAP fault XML, verify the handler returns the SOAP fault text rather than a generic HTTP status error.
+- [ ] Add a test: mock CIIMS returns `200 OK`, verify `Send()` succeeds normally.
+
+### Phase 2 — Performance (High Priority)
+
+#### 3. Harden Response Parsing and Pre-compile Patterns
+
+- [ ] Prefer replacing regex-based parsing in `GetMsgs` and `GetErrMsg` with `encoding/xml.Decoder` token parsing that matches elements by local name (`string`, `errorMessage`) regardless of namespace prefix.
+- [ ] If regex is retained as a short-term step, update patterns to handle expected formatting variations such as attributes on `<prefix:string>` and multiline content.
+- [ ] If regex is retained, move `regexp.MustCompile(msgExp)` and `regexp.MustCompile(errExp)` from function bodies to package-level `var` declarations.
+- [ ] Name them `msgRegex` and `errRegex`.
+- [ ] Update `GetMsgs` and `GetErrMsg` to use the pre-compiled variables.
+- [ ] Add tests for multiline string payloads, attributes on string elements, whitespace variations, and different namespace prefixes.
+- [ ] Verify all existing tests pass without changes unless parser behavior is intentionally broadened.
+
+#### 4. Inject a Configured HTTP Client
+
+- [ ] Do **not** introduce package-level mutable client state such as `var httpClient *http.Client` plus `InitClient`; this risks nil-client bugs and test pollution.
+- [ ] In `internal/http.go`, introduce a transport type such as `type Client struct { httpClient *http.Client }`.
+- [ ] Add `NewClient(timeoutSec int) (*Client, error)` to validate/default the timeout and construct the underlying `http.Client`.
+- [ ] Move outbound send behavior to a method such as `func (c *Client) Send(url, msg string) (string, error)`.
+- [ ] Construct the client in `main()` after resolving configuration and pass it to handlers through a `Config`/handler struct or closure.
+- [ ] Update tests to create their own `internal.Client` instances so timeout settings do not leak between tests.
+- [ ] Add a test that verifies the injected client timeout is honored.
+- [ ] Ensure the existing `TestSend_NetworkTimeout` test still passes.
+
+### Phase 3 — Modernization (Medium Priority)
+
+#### 5. Replace Deprecated `ioutil.ReadAll`
+
+- [ ] In `internal/http.go`, replace `ioutil.ReadAll(resp.Body)` with `io.ReadAll(resp.Body)`.
+- [ ] Remove the `"io/ioutil"` import and add `"io"`.
+- [ ] Verify build and tests pass.
+
+#### 6. Add Handler-Level Tests
+
+- [ ] Create `cmd/main/main_test.go` with Gin's `httptest` setup.
+- [ ] Test `POST /send` with valid JSON → mock CIIMS returns success → assert `200 {"error":""}`.
+- [ ] Test `POST /send` with valid JSON → mock CIIMS returns SOAP fault → assert `500` with fault text.
+- [ ] Test `POST /send` with missing required field → assert `400`.
+- [ ] Update handlers to detect `*http.MaxBytesError` from binding and return `http.StatusRequestEntityTooLarge`.
+- [ ] Test `POST /send` with body exceeding 1 MB → assert `413`.
+- [ ] Test `POST /receive` with valid JSON → mock CIIMS returns messages → assert `200 {"msgs":[...]}`.
+- [ ] Test `POST /receive` with `count` = 0 → assert `400`.
+- [ ] Test `POST /receive` with `count` = 1001 → assert `400`.
+- [ ] Test `POST /receive` with valid JSON → mock CIIMS returns SOAP fault → assert `500`.
+- [ ] Test `GET /ping` → assert `200 {"message":"pong"}`.
+
+### Phase 4 — Abstraction (Low Priority)
+
+#### 7. Introduce Domain Types
+
+- [ ] In `internal/codec.go`, define a `CIIMSResponse` struct with a `RawXML string` field.
+- [ ] Add methods: `IsFault() bool`, `ErrorMessage() string`, `Messages() []string`.
+- [ ] Update the injected client's `Send()` method to return `(*CIIMSResponse, error)` instead of `(string, error)`.
+- [ ] Preserve access to any non-2xx response body through `CIIMSResponse.RawXML` and/or the typed status error so SOAP faults in HTTP 500 responses remain parseable.
+- [ ] Update `sendMessage` and `receiveMessage` to use the new methods.
+- [ ] Update all tests to use the new return type.
+- [ ] Ensure no change in external behavior.
+
+#### 8. Introduce a `Config` Struct
+
+- [ ] In `cmd/main/main.go`, define a `Config` struct with fields `ServerURL`, `Timeout`, `Listen`.
+- [ ] Include the injected CIIMS client/transport in `Config` or in a handler struct.
+- [ ] Parse environment variables into a `Config` value in `main()`.
+- [ ] Pass `Config` to handler functions via closure (or a handler struct).
+- [ ] Remove package-level `defaultURL` and `timeout` variables.
+- [ ] Update `getURL` to accept the server URL as a parameter.
+- [ ] Verify all handler tests pass with the new structure.
+
+#### 9. Remove Redundant `Send` Wrapper
+
+- [ ] In `internal/http.go`, delete `postSim` after moving its logic into the injected client method.
+- [ ] Decide whether to keep a package-level `Send(url, message, timeout)` compatibility wrapper for legacy internal tests; if kept temporarily, mark it as a thin compatibility helper and keep production handlers on the injected client.
+- [ ] Otherwise, update all callers (in `main.go` and tests) to use `client.Send(...)`.
+- [ ] Verify build and all tests pass.
+
+### Phase 5 — Cleanup (Low Priority)
+
+#### 10. Normalize Template Indentation
+
+- [ ] Confirm this is acceptable as a byte-for-byte SOAP request change before implementing.
+- [ ] In `internal/codec.go`, make `sendtpl` and `receivetpl` use consistent indentation (all spaces or all tabs).
+- [ ] Update the golden-file test constants in `internal/codec_test.go` (`SendEsp`, `ReceiveEsp`) to match.
+- [ ] Verify `TestSend` and `TestReceive` pass with the updated expected strings.
+
+#### 11. Remove Unused `gommon/log` Dependency
+
+- [ ] In `cmd/main/main.go`, replace `github.com/labstack/gommon/log` with Go's standard `log` package.
+- [ ] Replace `log.Infof` → `log.Printf`, `log.Errorf` → `log.Printf("[ERROR] ...")` or use `log` with prefixes.
+- [ ] Remove `github.com/labstack/gommon` from `go.mod` and run `go mod tidy`.
+- [ ] Verify build and all tests pass.
+
+---
+
+## Verification Criteria
+
+- [ ] `POST /receive` with a CIIMS SOAP fault returns `500 {"error":"<fault text>"}`, not `200 {"msgs":[]}`.
+- [ ] CIIMS returning HTTP 500 produces an error from `Send()`, not a successful response.
+- [ ] CIIMS returning HTTP 500 with a SOAP fault body returns the SOAP fault text to the caller.
+- [ ] Oversized request bodies return `413`, not a generic `400`.
+- [ ] `go test ./...` shows all tests passing; response parsing handles multiline/attribute/namespace-prefix variations.
+- [ ] HTTP client timeout is configured through an injected client/transport and does not rely on package-level mutable initialization.
+- [ ] `ioutil.ReadAll` no longer appears in the codebase.
+- [ ] `cmd/main/main_test.go` exists with at least 9 handler-level tests covering all error paths.
+- [ ] `internal.CIIMSResponse` type exists with `IsFault()`, `ErrorMessage()`, `Messages()` methods.
+- [ ] `cmd/main` has no package-level `defaultURL` or `timeout` variables.
+- [ ] `internal/http.go` has no `postSim`; production code uses the injected client `Send` method.
+- [ ] `sendtpl` and `receivetpl` use consistent indentation only if the wire-format change was explicitly accepted.
+- [ ] `github.com/labstack/gommon` is absent from `go.mod`.
+- [ ] `go vet ./...` and `go build ./...` produce no errors.
+
+---
+
+## Execution Order
+
+```
+Phase 1 (Correctness) ──► Phase 2 (Performance) ──► Phase 3 (Modernization)
+                                                            │
+Phase 5 (Cleanup) ◄──────── Phase 4 (Abstraction) ◄────────┘
+```
+
+Phases 1 and 2 should be completed first as they fix remaining bugs and transport/testability issues. Phase 4's `Config`/injected-client work may be pulled earlier if it simplifies Phase 2. Phases 3–5 are quality-of-life improvements that can be done in any order, but Phase 4 should precede Phase 5 since removing `gommon/log` may be affected by the `Config` struct refactor.
+
+---
+
+## Potential Risks and Mitigations
+
+1. **HTTP status code checking breaks CIIMS compatibility**
+   - Some SOAP services return `500` with a SOAP fault in the body (which is valid SOAP). The current code already handles this via `GetErrMsg`. The fix should check for 2xx and treat everything else as a transport error, but still allow the SOAP fault body to be extracted if present.
+   - Mitigation: On non-2xx, return a typed `HTTPStatusError` that exposes the response body and also return/preserve that body in the response value. The handler must parse SOAP faults first, then fall back to the status error.
+
+2. **Injected `http.Client` changes timeout behavior**
+   - The current code creates a new client per request with the configured timeout. An injected client has a fixed timeout set at construction.
+   - Mitigation: This is the desired production behavior, and tests should construct isolated clients. If per-request timeout overrides are needed later, use `context.WithTimeout` on the request context.
+
+3. **`CIIMSResponse` abstraction changes the return type**
+   - All callers of `Send()` must be updated.
+   - Mitigation: This is a mechanical refactor. The compiler will catch all call sites. Update them in one pass.
+
+4. **Removing `gommon/log` changes log output format**
+   - Standard `log` package has a different default format (timestamps with date/time).
+   - Mitigation: This is acceptable—Gin already uses its own logger. Standardizing on `log` reduces dependencies and is more idiomatic.
+
+5. **Template indentation change breaks golden-file tests**
+   - `TestSend` and `TestReceive` do exact string comparison.
+   - Mitigation: Update the expected constants (`SendEsp`, `ReceiveEsp`) in the same commit. The tests themselves verify correctness.