Reject timestamp name set while rows are buffered

QwpTableBuffer.setDesignatedTimestampName guarded only the rename
branch on rowCount, so a first set was accepted with rows already
buffered. On the UDP sender, TableOptionsImpl.designatedTimestamp
then bumped committedDatagramEstimate by the trailer size without
flushing or re-checking the cap. Since only commitCurrentRow checks
maxDatagramSize, a subsequent flush() shipped a datagram exceeding
the configured cap: IP fragmentation, or EMSGSIZE and silent data
loss near the 65507-byte limit.

setDesignatedTimestampName now rejects a first set while the buffer
holds rows, symmetric with the rename guard. This makes the estimate
bump in TableOptionsImpl unreachable, so this commit deletes it and
keeps only the base-estimate invalidation. Javadocs on QwpTableBuffer
and Sender.TableOptions now state the name may be set or re-declared
only while the table has no buffered rows.

Regression tests cover the buffer-level throw and the sender-level
scenario: the late set throws, the flushed datagram carries no
table-options trailer, and all packets stay within maxDatagramSize.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: jerrinot

core/src/main/java/io/questdb/client/Sender.java

@@ -870,9 +870,9 @@ interface TableOptions {
          * silently ignore it and create the conventional {@code timestamp}
          * column instead.
          * <p>
-         * The hint is sticky per table. It may be re-declared with a different
-         * name while the table has no buffered rows; changing it while rows
-         * are buffered throws.
+         * The hint is sticky per table. It may be set or re-declared only
+         * while the table has no buffered rows; setting it while rows are
+         * buffered throws.
          *
          * @param columnName non-empty column name of at most 127 UTF-8 bytes
          * @return this instance for method chaining

core/src/main/java/io/questdb/client/cutlass/qwp/client/QwpUdpSender.java

@@ -1548,20 +1548,14 @@ public TableOptions designatedTimestamp(CharSequence columnName) {
                         "table options reference is stale; call tableOptions() after table()"
                 );
             }
-            String previousName = tableBuffer.getDesignatedTimestampName();
             tableBuffer.setDesignatedTimestampName(columnName);
             // The cached base estimate folds in the trailer size, which depends on
-            // the name length, so every accepted set/change must invalidate it. The
-            // committedDatagramEstimate bump stays under previousName == null: a name
-            // change requires rowCount == 0, where the committed estimate is already 0.
+            // the name length, so every accepted set/change must invalidate it. Any
+            // accepted set requires rowCount == 0, where the committed estimate is
+            // already 0, so no committedDatagramEstimate adjustment is needed.
             if (currentTableHeadroomState != null) {
                 currentTableHeadroomState.invalidateBaseEstimate();
             }
-            if (previousName == null && trackDatagramEstimate && committedDatagramEstimate > 0) {
-                committedDatagramEstimate += QwpColumnWriter.getSingleTableOptionsTrailerSize(
-                        tableBuffer.getDesignatedTimestampName()
-                );
-            }
             return this;
         }
 

core/src/main/java/io/questdb/client/cutlass/qwp/protocol/QwpTableBuffer.java

@@ -366,8 +366,8 @@ public void rollbackUncommittedColumns() {
     /**
      * Sets the create-only designated timestamp column name hint for this
      * table. The value is sticky across rows and buffer resets. It may be
-     * re-declared while the buffer holds no rows; changing it while rows are
-     * buffered throws.
+     * set or re-declared only while the buffer holds no rows; any set while
+     * rows are buffered throws.
      *
      * @param columnName non-empty name of at most 127 UTF-8 bytes
      */
@@ -383,6 +383,12 @@ public void setDesignatedTimestampName(CharSequence columnName) {
             );
         }
         if (designatedTimestampName == null) {
+            if (rowCount != 0) {
+                throw new LineSenderException(
+                        "cannot set designated timestamp name for table '" + tableName
+                                + "' after rows are buffered [new=" + columnName + ']'
+                );
+            }
             designatedTimestampName = Chars.toString(columnName);
         } else if (!Chars.equals(designatedTimestampName, columnName)) {
             if (rowCount != 0) {

core/src/test/java/io/questdb/client/test/cutlass/qwp/client/QwpUdpSenderTest.java

@@ -1729,6 +1729,33 @@ public void testTableOptionsDesignatedTimestampEmitsTrailer() throws Exception {
         });
     }
 
+    @Test
+    public void testTableOptionsDesignatedTimestampRejectedAfterRowsBuffered() throws Exception {
+        assertMemoryLeak(() -> {
+            CapturingNetworkFacade nf = new CapturingNetworkFacade();
+            int maxDatagramSize = 1024;
+            try (QwpUdpSender sender = new QwpUdpSender(nf, 0, 0, 9000, 1, maxDatagramSize)) {
+                sender.table("t");
+                sender.longColumn("x", 1).atNow();
+
+                // a late hint would grow the committed datagram past the cap
+                // with no re-check on the flush path, so it must be rejected
+                assertThrowsContains(
+                        "after rows are buffered",
+                        () -> sender.tableOptions().designatedTimestamp("event_ts")
+                );
+
+                sender.flush();
+                Assert.assertEquals(1, nf.packets.size());
+                Assert.assertEquals(0, (byte) (nf.packets.get(0)[HEADER_OFFSET_FLAGS] & FLAG_TABLE_OPTIONS));
+                assertPacketsWithinLimit(new RunResult(nf.packets, nf.lengths, nf.sendCount), maxDatagramSize);
+
+                // rowCount == 0 after the flush: the hint is accepted again
+                sender.tableOptions().designatedTimestamp("event_ts");
+            }
+        });
+    }
+
     @Test
     public void testTableOptionsOnlyRowIsDiscarded() throws Exception {
         assertMemoryLeak(() -> {

core/src/test/java/io/questdb/client/test/cutlass/qwp/protocol/QwpTableBufferTest.java

@@ -1371,6 +1371,27 @@ public void testRetainInProgressRowFastClearsUnstagedNullableColumn() throws Exc
         });
     }
 
+    @Test
+    public void testDesignatedTimestampNameFirstSetAfterRowsBufferedThrows() throws Exception {
+        assertMemoryLeak(() -> {
+            try (QwpTableBuffer table = new QwpTableBuffer("test")) {
+                table.getOrCreateColumn("x", QwpConstants.TYPE_LONG, false).addLong(1);
+                table.nextRow();
+                try {
+                    table.setDesignatedTimestampName("event_time");
+                    fail("expected rejection of first set after rows are buffered");
+                } catch (LineSenderException e) {
+                    assertTrue(e.getMessage().contains("after rows are buffered"));
+                }
+                assertNull(table.getDesignatedTimestampName());
+
+                table.reset();
+                table.setDesignatedTimestampName("event_time");
+                assertEquals("event_time", table.getDesignatedTimestampName());
+            }
+        });
+    }
+
     @Test
     public void testDesignatedTimestampNameIsStickyAndConsistent() throws Exception {
         assertMemoryLeak(() -> {