Ryan Malloy
f202dbce0c
Project goal: pure-Python implementation of the Informix SQLI wire protocol. No CSDK, no JVM, no native deps. Targets icr.io/informix /informix-developer-database (port 9088) as the dev/test instance. Phase 0 is a documentation-only spike that gates all implementation work. The four scaffolds: - README.md: project status and Phase 0 deliverable index - docs/PROTOCOL_NOTES.md: byte-level wire-format reference (TBD) - docs/JDBC_NOTES.md: reverse-lookup index into the decompiled IBM JDBC driver (4.50.4.1), populated from build/jdbc-src/ once the decompile lands - docs/DECISION_LOG.md: running rationale, with the Phase-1 paramstyle /Python-floor/autocommit decisions pre-locked so they don't churn later CLAUDE.md is gitignored — operator-private context, public-PyPI repo.
164 lines
3.7 KiB
Markdown
164 lines
3.7 KiB
Markdown
# SQLI Wire Protocol Notes
|
|
|
|
> **Phase 0 spike artifact.** This is the byte-level reference document for the Informix SQLI wire protocol, derived from a combination of packet captures against the IBM Informix Developer Edition Docker image and clean-room study of the decompiled IBM JDBC driver (`com.ibm.informix:jdbc:4.50.4.1`). It is the canonical reference that all subsequent implementation phases depend on.
|
|
>
|
|
> **Current state**: scaffold only. Sections fill in as the spike proceeds.
|
|
|
|
---
|
|
|
|
## Source attribution conventions
|
|
|
|
Each documented byte sequence cites both sources of evidence:
|
|
|
|
- 🔵 **PCAP**: observed in `docs/CAPTURES/<file>.pcap` at offset `<n>`
|
|
- 🟡 **JDBC**: cross-referenced against `<class>.<method>()` in the decompiled tree (see `JDBC_NOTES.md`)
|
|
|
|
A finding is considered *confirmed* only when 🔵 and 🟡 corroborate. Single-source observations are flagged 🟠 *unverified*.
|
|
|
|
---
|
|
|
|
## 1. Connection establishment
|
|
|
|
### TCP setup
|
|
- Port: 9088 (SQLI native, default)
|
|
- Protocol: TCP, no TLS in plain mode
|
|
- Who speaks first: TBD
|
|
|
|
### Initial banner / capability exchange
|
|
TBD
|
|
|
|
---
|
|
|
|
## 2. Login sequence
|
|
|
|
### Message ordering
|
|
TBD
|
|
|
|
### Login packet structure
|
|
| Offset | Width | Field | Notes |
|
|
|--------|-------|-------|-------|
|
|
| TBD | TBD | TBD | TBD |
|
|
|
|
### Username encoding
|
|
TBD
|
|
|
|
### Password encoding (plain auth, no obfuscation)
|
|
TBD
|
|
|
|
### Database selection
|
|
TBD (during login, or separate USE-DATABASE message?)
|
|
|
|
### Server response on success
|
|
TBD
|
|
|
|
### Server response on auth failure
|
|
TBD
|
|
|
|
---
|
|
|
|
## 3. Message framing
|
|
|
|
### Header layout
|
|
TBD — fields: type tag, length, flags?
|
|
|
|
### Length field
|
|
- Width: TBD bytes
|
|
- Endianness: TBD
|
|
- Value semantics: payload-only or whole-message?
|
|
|
|
### Endianness (overall)
|
|
TBD
|
|
|
|
### Message type tags
|
|
| Tag (hex) | Direction | Name | Purpose |
|
|
|-----------|-----------|------|---------|
|
|
| TBD | TBD | TBD | TBD |
|
|
|
|
---
|
|
|
|
## 4. Statement execution: `SELECT 1`
|
|
|
|
### Request
|
|
TBD
|
|
|
|
### Response
|
|
TBD
|
|
|
|
### Type code observed for the literal `1`
|
|
TBD
|
|
|
|
---
|
|
|
|
## 5. Result-set framing
|
|
|
|
### Column descriptor block
|
|
TBD — fields per column: name, type code, precision/scale, nullability flag, …
|
|
|
|
### Row encoding
|
|
TBD — fixed-position fields? null bitmap? per-field length prefix?
|
|
|
|
### End-of-result marker
|
|
TBD
|
|
|
|
---
|
|
|
|
## 6. Error responses
|
|
|
|
### Error packet format
|
|
TBD — fields: SQLSTATE, native error code, message text
|
|
|
|
### Encoding
|
|
TBD
|
|
|
|
---
|
|
|
|
## 7. Disconnection
|
|
|
|
### Client→server logout message
|
|
TBD
|
|
|
|
### Server-side close behavior
|
|
TBD
|
|
|
|
---
|
|
|
|
## 8. Type codecs
|
|
|
|
### IDS type codes observed in column descriptors
|
|
|
|
| Code (decimal/hex) | IDS Type | Wire format | Notes |
|
|
|--------------------|----------|-------------|-------|
|
|
| TBD | SMALLINT | TBD | |
|
|
| TBD | INTEGER | TBD | |
|
|
| TBD | BIGINT | TBD | |
|
|
| TBD | FLOAT | TBD | |
|
|
| TBD | CHAR | TBD | |
|
|
| TBD | VARCHAR | TBD | |
|
|
| TBD | BOOLEAN | TBD | |
|
|
| TBD | DATE | TBD | 4-byte day count from 1899-12-31 (Informix epoch); confirm |
|
|
|
|
(DATETIME, INTERVAL, DECIMAL, BLOBs etc. are out of scope for Phase 0; see `DECISION_LOG.md`.)
|
|
|
|
---
|
|
|
|
## 9. Open questions
|
|
|
|
> List things observed in JDBC source or packet captures that we don't yet understand. Each entry is either resolved-and-removed or escalated to `DECISION_LOG.md` as a deferred item.
|
|
|
|
- _(none yet)_
|
|
|
|
---
|
|
|
|
## 10. Cross-checks
|
|
|
|
### JDBC ↔ PCAP corroboration matrix
|
|
|
|
| Phase 0 milestone | JDBC source confirms | PCAP confirms | Status |
|
|
|-------------------|----------------------|---------------|--------|
|
|
| Login byte layout | ⬜ | ⬜ | pending |
|
|
| `SELECT 1` round-trip | ⬜ | ⬜ | pending |
|
|
| Error response structure | ⬜ | ⬜ | pending |
|
|
| Disconnection | ⬜ | ⬜ | pending |
|
|
|
|
Phase 0 exit requires all four rows = ✅✅ confirmed.
|