ciimsproxy/plans/2026-07-08-ciimsproxy-codebase-analysis.md

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

// 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.