Skip to content

Commit 6004261

Browse files
morningmanclaude
andauthored
[test](protocol) Record a golden baseline of MySQL packets and Arrow Flight results (#67789)
### What problem does this PR solve? Issue Number: #67577 -- the tracking issue for the protocol-agnostic session and execution layer. This is the first PR of its Stage 1 and does not close it. **In plain terms.** Nothing in this repository checks the bytes the server sends to a client. Tests stop at "the statement succeeded and the result had two rows"; how many packets carried it, in what order, with which sequence ids, whether the result set ended in an EOF or an OK, and whether it was flushed, is checked by nobody. The next PRs move the MySQL and the Arrow Flight SQL front ends onto one shared session layer, which must not change a single byte on the wire -- but if one of them drops a packet or reorders two, every existing test still passes and the only symptom is a client that hangs, weeks later, with no way to tell which refactor did it. So this PR records what the server sends today into two checked-in files, before anything moves. From then on, a change to those bytes turns a test red and names the exact line and byte that moved. It touches no production code -- it photographs the rooms before the renovation starts. Problem Summary: Nothing in the tree asserts the bytes a MySQL client actually receives, or the Arrow batches an Arrow Flight SQL client actually receives. Every test around the frontend's result path stops at the `QueryState` or at a `ShowResultSet`; the packet framing below that -- how many packets, in what order, with which sequence ids, terminated by an EOF or an OK, flushed where -- is only exercised by real clients in the regression suites, and only for the handful of statements those suites run. That gap is about to matter. The session and result layers are being reorganized so that MySQL and Arrow Flight SQL become two front ends over one session (the follow-up PRs extract a protocol adapter and a result sender out of `ConnectContext`, `ConnectProcessor` and `StmtExecutor`). Those are pure refactors, and a pure refactor that drops an EOF packet, reorders a column definition, or shifts a sequence id passes every existing unit test and shows up only as a client that hangs. This PR takes the baseline first, before anything moves. It adds no production code. ### What is changed? Four test classes under `fe/fe-core/src/test/java/org/apache/doris/qe/protocol/` and two golden files under `fe/fe-core/src/test/resources/protocol-golden/`: - `RecordingMysqlChannel` -- a `DummyMysqlChannel` that plays canned request packets and records every response packet: its payload, the sequence id it was framed with, and whether the response was flushed at it. The sequence id is advanced the way the real channel advances it (once per packet read, once per packet written), so what is recorded is what would reach the wire. - `ProtocolGolden` -- renders the recorded traffic as an annotated hexdump and compares it with the checked-in file. On a mismatch it writes the current traffic to `target/protocol-golden/<name>` and names it in the failure message, the same convention `AccessControlBehaviorBaselineTest` uses. - `MysqlPacketGoldenTest` -- 27 cases: constant selects, a NULL literal, an empty result set, `SHOW VARIABLES`, `DESC` (the one case whose row stream is longer than a single packet), `SET`, `USE`, `EXPLAIN`, a syntax error, an unknown table, an error followed by a healthy statement on the same connection, multi-statement requests with and without `CLIENT_MULTI_STATEMENTS`, and the connection commands (`COM_FIELD_LIST`, `COM_STMT_PREPARE`, `COM_STMT_CLOSE`, `COM_SET_OPTION`, `COM_RESET_CONNECTION`, `COM_PING`, `COM_INIT_DB`, `COM_STATISTICS`, an unknown command, `COM_QUIT`). Two of them run with `CLIENT_DEPRECATE_EOF` negotiated off, the capability that decides whether a result set ends in an EOF or an OK and whether the column definitions get their own terminator. - `FlightResultGoldenTest` -- the same statements an Arrow Flight SQL session can be answered frontend-side, recorded as the schema and rows of the `VectorSchemaRoot` the session caches, or as the error it failed with. Capability negotiation is replayed rather than mocked: the test derives the effective capability the way `MysqlProto.negotiate()` does (`server & client`) and sets `clientDeprecatedEOF`, `clientMultiStatements` and the serializer capability from it, so the recorded packets match what a real connection with those flags would produce. Two responses are recorded as shape rather than bytes, because their payload legitimately moves with changes that have nothing to do with the protocol: a parser error carries the entire keyword list of the grammar (4881 bytes today), and an `EXPLAIN` carries the current plan text. For those the golden keeps the packet kinds, plus the error code, SQL state and the start of the message. The statement set is limited to what a frontend answers on its own. `COM_STMT_EXECUTE` is deliberately absent: `ConnectContext.supportHandleByFe()` is false for it, so its result always comes from a backend and belongs in `prepared_stmt_p0`, not here. No case in either test reaches a backend (verified: the mocked backend logs no `exec_plan_fragment` request during the run). The two golden files are added to `.licenserc.yaml`'s `paths-ignore`: both tests regenerate the file in full and compare it byte for byte, so a license header would be read back as unexpected content. ### Release note None. ### Check List (For Author) - Test - [x] Unit Test - [ ] Regression test - [ ] Manual test (add detailed scripts or steps below) - [ ] No need to test or manual test. Explain why: - Behavior changed: - [x] No. - [ ] Yes. - Does this need documentation? - [x] No. - [ ] Yes. Co-authored-by: Claude Opus 5 (1M context) <[email protected]>
1 parent 5985916 commit 6004261

7 files changed

Lines changed: 1266 additions & 0 deletions

File tree

‎.licenserc.yaml‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -64,6 +64,11 @@ header:
6464
# the whole file and compares it to this one line for line, so a header would read back
6565
# as extra rows; it prints the regenerated path on mismatch instead.
6666
- "fe/fe-core/src/test/resources/access-control-behavior-baseline.txt"
67+
# Golden protocol traffic. MysqlPacketGoldenTest and FlightResultGoldenTest regenerate
68+
# each file in full and compare it to this one byte for byte, so a header would read back
69+
# as unexpected leading content; both tests print the regeneration command on mismatch.
70+
- "fe/fe-core/src/test/resources/protocol-golden/mysql-packets.txt"
71+
- "fe/fe-core/src/test/resources/protocol-golden/flight-results.txt"
6772
# Connector plugin settings templates. build.sh seeds each connector's live
6873
# <name>.conf from its template verbatim (cp -n), so the template's content IS
6974
# the file an administrator edits in plugins/connector/<dir>/. Matched by name
Lines changed: 205 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,205 @@
1+
// Licensed to the Apache Software Foundation (ASF) under one
2+
// or more contributor license agreements. See the NOTICE file
3+
// distributed with this work for additional information
4+
// regarding copyright ownership. The ASF licenses this file
5+
// to you under the Apache License, Version 2.0 (the
6+
// "License"); you may not use this file except in compliance
7+
// with the License. You may obtain a copy of the License at
8+
//
9+
// http://www.apache.org/licenses/LICENSE-2.0
10+
//
11+
// Unless required by applicable law or agreed to in writing,
12+
// software distributed under the License is distributed on an
13+
// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
14+
// KIND, either express or implied. See the License for the
15+
// specific language governing permissions and limitations
16+
// under the License.
17+
18+
package org.apache.doris.qe.protocol;
19+
20+
import org.apache.doris.analysis.UserIdentity;
21+
import org.apache.doris.catalog.Env;
22+
import org.apache.doris.common.util.DebugUtil;
23+
import org.apache.doris.qe.QueryState.MysqlStateType;
24+
import org.apache.doris.service.arrowflight.FlightSqlConnectProcessor;
25+
import org.apache.doris.service.arrowflight.results.FlightSqlResultCacheEntry;
26+
import org.apache.doris.service.arrowflight.sessions.FlightSqlConnectContext;
27+
import org.apache.doris.utframe.TestWithFeService;
28+
29+
import com.google.common.collect.Lists;
30+
import org.apache.arrow.vector.FieldVector;
31+
import org.apache.arrow.vector.VarCharVector;
32+
import org.apache.arrow.vector.VectorSchemaRoot;
33+
import org.apache.arrow.vector.types.pojo.Field;
34+
import org.junit.jupiter.api.Test;
35+
36+
import java.nio.charset.StandardCharsets;
37+
import java.util.List;
38+
39+
/**
40+
* Records what an Arrow Flight SQL session gets back for the statements a frontend answers itself,
41+
* and compares it with a golden file.
42+
*
43+
* <p>Counterpart of {@link MysqlPacketGoldenTest}: the two protocols are being moved onto one
44+
* session and one result path, so both ends need a baseline taken before the move. What a Flight
45+
* client sees is the cached {@code VectorSchemaRoot} -- its schema and its rows -- or the error the
46+
* statement failed with, so that is what this records.
47+
*
48+
* <p>Only statements a frontend can answer are covered. An Arrow Flight session never handles a
49+
* query in the frontend ({@code ConnectContext.supportHandleByFe()} is false for it), so a
50+
* {@code SELECT} reaches a backend and produces endpoints instead of a cached result; those belong
51+
* in the {@code arrow_flight_sql_p0} regression suite.
52+
*
53+
* <p>What is covered: {@code SHOW VARIABLES}, {@code SHOW DATABASES} and {@code DESC} (results the
54+
* frontend materializes and caches), {@code SET} and {@code USE} (no cached result, which is how the
55+
* producer knows to synthesize its {@code StatusResult=0} row), {@code EXPLAIN}, a syntax error and
56+
* an unknown table. Every column comes back as {@code Utf8} today -- that is the current behavior,
57+
* and typing those results is a later step of the same work.
58+
*
59+
* <p>Regenerate from the {@code fe} directory with:
60+
* {@code mvn test -pl fe-common,fe-core -am -Dtest=FlightResultGoldenTest
61+
* -Ddoris.protocol.golden.regenerate=true} -- {@code -am} is required, the reactor does not
62+
* resolve {@code ${revision}} without it.
63+
*/
64+
public class FlightResultGoldenTest extends TestWithFeService {
65+
private static final String GOLDEN_FILE = "flight-results.txt";
66+
private static final String DB_NAME = "protocol_golden_flight_db";
67+
private static final String TABLE_NAME = "golden_tbl";
68+
private static final String PEER_IDENTITY = "protocol-golden-peer";
69+
private static final int MESSAGE_PREFIX_LENGTH = 72;
70+
71+
@Override
72+
protected void runBeforeAll() throws Exception {
73+
createDatabaseAndUse(DB_NAME);
74+
createTable("create table " + TABLE_NAME + " (k1 int, k2 varchar(32)) duplicate key(k1)"
75+
+ " distributed by hash(k1) buckets 1 properties('replication_num' = '1');");
76+
}
77+
78+
@Test
79+
public void testFlightResultGolden() throws Exception {
80+
StringBuilder actual = new StringBuilder();
81+
for (FlightCase flightCase : cases()) {
82+
actual.append(render(flightCase.statement, flightCase.detail));
83+
}
84+
ProtocolGolden.verify(GOLDEN_FILE, actual.toString());
85+
}
86+
87+
private List<FlightCase> cases() {
88+
return Lists.newArrayList(
89+
new FlightCase("show variables like 'wait_timeout'", Detail.ROWS),
90+
new FlightCase("show databases like '" + DB_NAME + "'", Detail.ROWS),
91+
new FlightCase("desc " + TABLE_NAME, Detail.ROWS),
92+
new FlightCase("set sql_select_limit = 100", Detail.ROWS),
93+
new FlightCase("use " + DB_NAME, Detail.ROWS),
94+
// The plan text and the node ids inside it move with the planner, so only the shape
95+
// of the answer is recorded. Same reason as ProtocolGolden.Fidelity.SUMMARY.
96+
new FlightCase("explain select 1", Detail.SHAPE),
97+
// A parser error carries the whole keyword list of the grammar.
98+
new FlightCase("select from", Detail.SHAPE),
99+
new FlightCase("select * from no_such_table", Detail.ROWS));
100+
}
101+
102+
private String render(String statement, Detail detail) throws Exception {
103+
FlightSqlConnectContext ctx = newContext();
104+
StringBuilder rendered = new StringBuilder();
105+
rendered.append("=== statement ").append(statement).append(" ===\n");
106+
try (FlightSqlConnectProcessor processor = new FlightSqlConnectProcessor(ctx)) {
107+
processor.handleQuery(statement);
108+
rendered.append(renderOutcome(ctx, detail));
109+
} finally {
110+
connectContext.setThreadLocalInfo();
111+
}
112+
rendered.append('\n');
113+
return rendered.toString();
114+
}
115+
116+
private String renderOutcome(FlightSqlConnectContext ctx, Detail detail) {
117+
StringBuilder rendered = new StringBuilder();
118+
if (ctx.getState().getStateType() == MysqlStateType.ERR) {
119+
String message = ctx.getState().getErrorMessage().replace("\n", "\\n").replace("\r", "\\r");
120+
if (detail == Detail.SHAPE && message.length() > MESSAGE_PREFIX_LENGTH) {
121+
message = message.substring(0, MESSAGE_PREFIX_LENGTH) + "...";
122+
}
123+
rendered.append("state: ERR errorCode=").append(ctx.getState().getErrorCode())
124+
.append(" message=\"").append(message).append("\"\n");
125+
return rendered.toString();
126+
}
127+
rendered.append("state: ").append(ctx.getState().getStateType()).append('\n');
128+
if (ctx.getFlightSqlChannel().resultNum() == 0) {
129+
// DorisFlightSqlProducer answers such a statement with a synthesized one-row
130+
// StatusResult=0; nothing was cached by the frontend itself.
131+
rendered.append("result: none, the producer synthesizes StatusResult=0\n");
132+
return rendered.toString();
133+
}
134+
FlightSqlResultCacheEntry entry = ctx.getFlightSqlChannel().getResult(DebugUtil.printId(ctx.queryId()));
135+
if (entry == null) {
136+
rendered.append("result: cached under an unexpected query id\n");
137+
return rendered.toString();
138+
}
139+
rendered.append(renderRoot(entry.getVectorSchemaRoot(), detail));
140+
return rendered.toString();
141+
}
142+
143+
private String renderRoot(VectorSchemaRoot root, Detail detail) {
144+
StringBuilder rendered = new StringBuilder();
145+
rendered.append("schema:\n");
146+
for (Field field : root.getSchema().getFields()) {
147+
rendered.append(" ").append(field.getName()).append(": ").append(field.getType())
148+
.append(field.isNullable() ? " nullable" : " not null").append('\n');
149+
}
150+
if (detail == Detail.SHAPE) {
151+
rendered.append("rows: ").append(root.getRowCount() > 0 ? "some" : "none").append('\n');
152+
return rendered.toString();
153+
}
154+
rendered.append("rows: ").append(root.getRowCount()).append('\n');
155+
for (int row = 0; row < root.getRowCount(); row++) {
156+
StringBuilder line = new StringBuilder();
157+
for (FieldVector vector : root.getFieldVectors()) {
158+
if (line.length() > 0) {
159+
line.append(" | ");
160+
}
161+
line.append(valueOf(vector, row));
162+
}
163+
// Trailing spaces would be an empty last column; keep them out of the file so an editor
164+
// or a whitespace lint cannot silently rewrite the golden.
165+
rendered.append(" ").append(line.toString().stripTrailing()).append('\n');
166+
}
167+
return rendered.toString();
168+
}
169+
170+
private String valueOf(FieldVector vector, int row) {
171+
if (vector.isNull(row)) {
172+
return "NULL";
173+
}
174+
if (vector instanceof VarCharVector) {
175+
return new String(((VarCharVector) vector).get(row), StandardCharsets.UTF_8);
176+
}
177+
return String.valueOf(vector.getObject(row));
178+
}
179+
180+
/** How much of a result to keep; see ProtocolGolden.Fidelity for why the second mode exists. */
181+
private enum Detail {
182+
ROWS,
183+
SHAPE
184+
}
185+
186+
private static class FlightCase {
187+
private final String statement;
188+
private final Detail detail;
189+
190+
FlightCase(String statement, Detail detail) {
191+
this.statement = statement;
192+
this.detail = detail;
193+
}
194+
}
195+
196+
private FlightSqlConnectContext newContext() {
197+
FlightSqlConnectContext ctx = new FlightSqlConnectContext(PEER_IDENTITY);
198+
ctx.setCurrentUserIdentity(UserIdentity.ROOT);
199+
ctx.setRemoteIP("127.0.0.1");
200+
ctx.setEnv(Env.getCurrentEnv());
201+
ctx.setDatabase(DB_NAME);
202+
ctx.setThreadLocalInfo();
203+
return ctx;
204+
}
205+
}

0 commit comments

Comments
 (0)