Files
qbit-document-generation/foundation/src/test/java/com/kingsrook/qbits/documentgeneration/MySqlGenerationQueueTest.java
T
james.maesandClaude Fable 5.2 9b908ac516 feat(foundation): a generation request names its render target (P7)
A request could not say which printer resolution to render a label for:
RenderRequest.targetDpi existed and nothing set it.

DocumentGenerationService.Request gains a trailing targetDpi (absent, 203,
300 or 600; every earlier constructor stays and means none). It is stored
in a new nullable column, target_dpi, on document_generation_request,
compared on retry and lookup beside destination, media and copies, framed
into the intent digest as target-dpi/v1 when stated, and passed to the
renderer. A request without a target has exactly the digest it had, so
earlier rows and their retries are unchanged; the same key with another
target, or with none, is another intent.

Nobody who asks for 300 dpi may silently get another resolution, so a
target is refused before any row exists when it cannot be honoured: for a
PDF, and for any renderer that does not declare the new
IsolatedRenderer.supportsRenderTarget() (false by default, so an adapter
written before the target cannot be handed one and ignore it).

A host applies one statement, from the shipped script for its database:
db/migrations/20261112-render-target-dpi-{h2,mysql,postgres}.sql
(ALTER TABLE document_generation_request ADD COLUMN target_dpi INTEGER
NULL). The generate process form offers the target and the request status
shows it. Batches, the queue and reprints carry none.

Also from the review of the ports: RenderRequest and PreviewRequest hold
their own unmodifiable copy of the context (null values allowed) and
print only their format and render target (and the request id), never the
record data or the template source. Neither wire form changes.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
2026-11-12 12:02:38 -06:00

380 lines
19 KiB
Java

/*
* QQQ - Low-code Application Framework for Engineers.
* Copyright (C) 2021-2025. Kingsrook, LLC
* 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
* contact@kingsrook.com
* https://github.com/Kingsrook/
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* https://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package com.kingsrook.qbits.documentgeneration;
import java.sql.Connection;
import java.util.List;
import com.kingsrook.qqq.backend.core.exceptions.QException;
import com.kingsrook.qqq.backend.module.rdbms.model.metadata.RDBMSBackendMetaData;
import org.junit.jupiter.api.AfterAll;
import org.junit.jupiter.api.AfterEach;
import org.junit.jupiter.api.BeforeAll;
import org.junit.jupiter.api.Test;
import static org.assertj.core.api.Assertions.assertThat;
import static org.assertj.core.api.Assertions.assertThatThrownBy;
/***************************************************************************
** Run the unchanged native authorization/transaction suite on real MySQL8.4.
***************************************************************************/
class MySqlGenerationQueueTest extends GenerationQueueJdbcTest
{
private static MySqlGenerationDatabase mysql;
/***********************************************************************
** One exact disposable engine per suite; all test cases use new schemas.
***********************************************************************/
@BeforeAll
static void startMySql()
{
mysql = new MySqlGenerationDatabase();
}
/***********************************************************************
** Remove only the fixture-owned engine after every inherited assertion.
***********************************************************************/
@AfterAll
static void stopMySql()
{
if(mysql != null)
{
mysql.close();
}
}
/***********************************************************************
** Preserve each completed case's provider state before later fixture work.
***********************************************************************/
@AfterEach
void observeCaseHealth()
{
mysql.observeHealth("after-case");
}
/***********************************************************************
** Native actions receive only the DML identity, never migration authority.
***********************************************************************/
@Override
protected RDBMSBackendMetaData database(String name, String defaultUrl) throws Exception
{
return (mysql.database(name));
}
/***********************************************************************
** Assertion and fault-injection connections remain separate from QQQ.
***********************************************************************/
@Override
protected Connection connection() throws Exception
{
return (mysql.connection());
}
/***********************************************************************
** Execute fixed fixture DDL, with no compatibility/emulation database mode.
***********************************************************************/
@Override
protected void sql(String source) throws Exception
{
mysql.sql(source);
}
/***********************************************************************
** The shipped migration scripts for this engine.
***********************************************************************/
@Override
protected String dialect()
{
return ("mysql");
}
/***********************************************************************
** Exercise the shipped native schema, including binary idempotency keys.
***********************************************************************/
@Override
protected String schema(DocumentGenerationQBitConfig configuration)
{
return (DocumentGenerationSchema.mysqlScript(configuration));
}
/***************************************************************************
** Actual cold server restart preserves committed results and untouched work.
***************************************************************************/
@Test
void serverRestartPreservesQueueAndIndependentAudit() throws Exception
{
int id = enqueue("restart");
var first = queue.advance(id);
assertThat(first.state()).isEqualTo("GENERATED");
mysql.restart(jdbcBackend);
assertThat(queue.status(id, -1, 10).items().getFirst()).isEqualTo(first);
assertThat(queue.advance(id).state()).isEqualTo("GENERATED");
assertThat(queue.advance(id)).isNull();
try(var connection = connection(); var statement = connection.createStatement();
var rows = statement.executeQuery("SELECT COUNT(*) FROM document_generation_event WHERE outcome='GENERATION_RETAINED'"))
{
rows.next();
assertThat(rows.getInt(1)).isEqualTo(2);
}
}
/***************************************************************************
** Binary NO PAD keys preserve distinct actor/request identity and exact retries.
***************************************************************************/
@Test
void caseAndTrailingSpaceRemainDistinctIdempotencyKeys() throws Exception
{
int upper = enqueue("Case");
int lower = enqueue("case");
int spaced = enqueue("Case ");
assertThat(List.of(upper, lower, spaced)).doesNotHaveDuplicates();
assertThat(enqueue("Case")).isEqualTo(upper);
}
/***************************************************************************
** Engine/collation/index drift is rejected before any native or queue write.
***************************************************************************/
@Test
void realSchemaDriftFailsClosed() throws Exception
{
sql("ALTER TABLE document_generation_stock ENGINE=MyISAM");
assertThatThrownBy(() -> enqueue("engine")).isInstanceOf(QException.class).hasMessageContaining("InnoDB");
assertThatThrownBy(() -> new DocumentDefinitionService(config).createType("must not persist")).isInstanceOf(QException.class).hasMessageContaining("InnoDB");
sql("ALTER TABLE document_generation_stock ENGINE=InnoDB");
sql("ALTER TABLE document_generation_queue MODIFY request_key VARCHAR(130) COLLATE utf8mb4_0900_ai_ci");
assertThatThrownBy(() -> enqueue("collation")).isInstanceOf(QException.class).hasMessageContaining("collation");
sql("ALTER TABLE document_generation_queue MODIFY request_key VARCHAR(130) COLLATE utf8mb4_0900_bin");
sql("ALTER TABLE document_generation_queue DROP INDEX uq_document_generation_queue_1");
assertThatThrownBy(() -> enqueue("index")).isInstanceOf(QException.class).hasMessageContaining("idempotency");
}
/***************************************************************************
** Flags are observed from the actual server, never assumed from fixture setup.
***************************************************************************/
@Test
void weakCommitSettingsAreRejectedBeforeWriting() throws Exception
{
try
{
sql("SET GLOBAL innodb_flush_log_at_trx_commit=2");
assertThatThrownBy(() -> enqueue("weak-redo")).isInstanceOf(QException.class).hasMessageContaining("synchronous MySQL");
sql("SET GLOBAL innodb_flush_log_at_trx_commit=1");
sql("SET GLOBAL sync_binlog=0");
assertThatThrownBy(() -> enqueue("weak-binlog")).isInstanceOf(QException.class).hasMessageContaining("synchronous MySQL");
sql("SET GLOBAL sync_binlog=1;SET GLOBAL innodb_doublewrite='DETECT_ONLY'");
assertThatThrownBy(() -> enqueue("detect-without-recovery")).isInstanceOf(QException.class).hasMessageContaining("doublewrite");
}
finally
{
sql("SET GLOBAL innodb_flush_log_at_trx_commit=1;SET GLOBAL sync_binlog=1;SET GLOBAL innodb_doublewrite='ON'");
}
assertThat(queue.status(enqueue("restored"), -1, 10).items()).hasSize(2);
}
/***************************************************************************
** Even a correct database cannot hide a non-UTC or non-strict session.
***************************************************************************/
@Test
void actualSessionPolicyAndDmlOnlyCredentialsAreVerified() throws Exception
{
try(var connection = connection(); var statement = connection.createStatement())
{
statement.execute("SET SESSION time_zone='+01:00'");
assertThatThrownBy(() -> GenerationJdbc.qualify(connection, jdbcBackend, true)).isInstanceOf(QException.class).hasMessageContaining("UTC");
statement.execute("SET SESSION time_zone='+00:00'");
statement.execute("SET SESSION sql_mode=''");
assertThatThrownBy(() -> GenerationJdbc.qualify(connection, jdbcBackend, true)).isInstanceOf(QException.class).hasMessageContaining("strict");
statement.execute("SET SESSION sql_mode='STRICT_TRANS_TABLES'");
statement.execute("SET SESSION transaction_read_only=1");
assertThatThrownBy(() -> GenerationJdbc.qualify(connection, jdbcBackend, true)).isInstanceOf(QException.class).hasMessageContaining("writable");
statement.execute("SET SESSION transaction_read_only=0");
statement.execute("SET SESSION innodb_lock_wait_timeout=50");
assertThatThrownBy(() -> GenerationJdbc.qualify(connection, jdbcBackend, true)).isInstanceOf(QException.class).hasMessageContaining("bounded");
statement.execute("SET SESSION innodb_lock_wait_timeout=5");
statement.execute("SET SESSION lock_wait_timeout=50");
assertThatThrownBy(() -> GenerationJdbc.qualify(connection, jdbcBackend, true)).isInstanceOf(QException.class).hasMessageContaining("bounded");
}
try(var connection = java.sql.DriverManager.getConnection(jdbcBackend.getJdbcUrl(), jdbcBackend.getUsername(), jdbcBackend.getPassword()); var statement = connection.createStatement())
{
assertThatThrownBy(() -> statement.execute("ALTER TABLE document_generation_stock ADD forbidden INT")).isInstanceOf(java.sql.SQLException.class);
}
}
/***************************************************************************
** Native metadata cannot redirect writes away from the tables being qualified
** and locked. No alias or alternate column is silently trusted.
***************************************************************************/
@Test
void rejectsNativePhysicalMappingDrift() throws Exception
{
var table = instance.getTable(GenerationTables.TEMPLATE);
var details = (com.kingsrook.qqq.backend.module.rdbms.model.metadata.RDBMSTableBackendDetails) table.getBackendDetails();
details.setTableName("other_template");
assertThatThrownBy(() -> new DocumentDefinitionService(config).createType("table drift"))
.isInstanceOf(QException.class).hasMessageContaining("native mapping");
details.setTableName(GenerationTables.TEMPLATE);
table.getField("pdfSource").setBackendName("other_source");
assertThatThrownBy(() -> enqueue("column-drift")).isInstanceOf(QException.class).hasMessageContaining("native mapping");
table.getField("pdfSource").setBackendName("pdf_source");
table.setPrimaryKeyField("stockId");
assertThatThrownBy(() -> enqueue("key-drift")).isInstanceOf(QException.class).hasMessageContaining("native mapping");
}
/***************************************************************************
** A real conflicting row lock produces a bounded refusal and no draft write.
***************************************************************************/
@Test
void templateLockContentionTimesOutWithoutChangingDraft() throws Exception
{
var definitions = new DocumentDefinitionService(config);
var original = definitions.loadDraft(template);
var session = com.kingsrook.qqq.backend.core.context.QContext.getQSession();
jdbcBackend.setJdbcUrl(jdbcBackend.getJdbcUrl() + "&sessionVariables=innodb_lock_wait_timeout=1,lock_wait_timeout=1");
long started = System.nanoTime();
try(var held = connection(); var statement = held.prepareStatement("SELECT id FROM document_generation_template WHERE id=? FOR UPDATE");
var executor = java.util.concurrent.Executors.newSingleThreadExecutor())
{
held.setAutoCommit(false);
statement.setInt(1, template);
try(var row = statement.executeQuery())
{
assertThat(row.next()).isTrue();
}
var attempt = executor.submit(() ->
{
com.kingsrook.qqq.backend.core.context.QContext.init(instance, session);
try
{
definitions.saveDraft(template, stock, new DocumentDefinitionService.Draft("must not save", null, null, List.of()), original.fingerprint());
return (null);
}
catch(QException refusal)
{
return (refusal);
}
finally
{
com.kingsrook.qqq.backend.core.context.QContext.clear();
}
});
try
{
QException refusal = attempt.get(8, java.util.concurrent.TimeUnit.SECONDS);
assertThat(refusal).isNotNull().hasMessageContaining("transactional row lock");
assertThat(refusal.getCause()).isInstanceOf(java.sql.SQLException.class);
assertThat(((java.sql.SQLException) refusal.getCause()).getErrorCode()).isEqualTo(1205);
}
finally
{
held.rollback();
}
}
assertThat(java.time.Duration.ofNanos(System.nanoTime() - started)).isLessThan(java.time.Duration.ofSeconds(8));
assertThat(definitions.loadDraft(template).fingerprint()).isEqualTo(original.fingerprint());
}
/***************************************************************************
** LONGTEXT stores bounded non-ASCII sources beyond MySQL's small TEXT limit.
***************************************************************************/
@Test
void largeUnicodeTemplateRoundTripsThroughNativePublication() throws Exception
{
var definitions = new DocumentDefinitionService(config);
String source = "<p>" + "Welcome café 東京 ".repeat(6000) + "</p>";
definitions.saveDraft(template, stock, new DocumentDefinitionService.Draft(source, null, null, List.of()));
int revision = definitions.publish(template);
assertThat(definitions.revision(revision).pdfSource()).isEqualTo(source);
}
/***************************************************************************
** A normal read after locking must see a concurrent commit, even after an
** earlier read. The same physical pooled connection restores its isolation
** after both successful commit and rollback; caller defaults are untouched.
***************************************************************************/
@Test
void freshLockedReadAndPhysicalPoolIsolationRestoration() throws Exception
{
com.kingsrook.qqq.backend.module.rdbms.jdbc.ConnectionManager.closeConnectionProviders();
jdbcBackend.setConnectionProvider(new com.kingsrook.qqq.backend.core.model.metadata.code.QCodeReference(
com.kingsrook.qqq.backend.module.rdbms.jdbc.C3P0PooledConnectionProvider.class));
jdbcBackend.setConnectionPoolSettings(new com.kingsrook.qqq.backend.module.rdbms.model.metadata.ConnectionPoolSettings()
.withInitialPoolSize(1).withMinPoolSize(1).withMaxPoolSize(1));
long physicalId;
int originalIsolation;
try(var connection = com.kingsrook.qqq.backend.module.rdbms.jdbc.ConnectionManager.getConnection(jdbcBackend))
{
physicalId = physicalId(connection);
originalIsolation = connection.getTransactionIsolation();
assertThat(originalIsolation).isEqualTo(Connection.TRANSACTION_REPEATABLE_READ);
}
GenerationStore.atomic(List.of(GenerationTables.TEMPLATE), () ->
{
var nativeTransaction = (com.kingsrook.qqq.backend.module.rdbms.actions.RDBMSTransaction) com.kingsrook.qqq.backend.core.context.QContext.getQBackendTransaction();
try
{
assertThat(physicalId(nativeTransaction.getConnection())).isEqualTo(physicalId);
assertThat(nativeTransaction.getConnection().getTransactionIsolation()).isEqualTo(Connection.TRANSACTION_READ_COMMITTED);
GenerationStore.get(GenerationTables.TEMPLATE, template);
sql("UPDATE document_generation_template SET pdf_source='separate committed edit' WHERE id=" + template);
GenerationStore.lockTemplate(template);
assertThat(GenerationStore.get(GenerationTables.TEMPLATE, template).getValueString("pdfSource")).isEqualTo("separate committed edit");
return (null);
}
catch(Exception failure)
{
throw new QException("Separate-connection isolation fixture failed.", failure);
}
});
assertPoolRestored(physicalId, originalIsolation);
assertThatThrownBy(() -> GenerationStore.atomic(List.of(GenerationTables.TEMPLATE), () ->
{
throw new QException("Deliberate rollback");
})).isInstanceOf(QException.class).hasMessageContaining("Deliberate rollback");
assertPoolRestored(physicalId, originalIsolation);
}
/***************************************************************************
** Prove restoration on the exact server session, not another pool member.
***************************************************************************/
private void assertPoolRestored(long expectedPhysicalId, int expectedIsolation) throws Exception
{
try(var connection = com.kingsrook.qqq.backend.module.rdbms.jdbc.ConnectionManager.getConnection(jdbcBackend))
{
assertThat(physicalId(connection)).isEqualTo(expectedPhysicalId);
assertThat(connection.getTransactionIsolation()).isEqualTo(expectedIsolation);
assertThat(connection.getAutoCommit()).isTrue();
}
assertThat(com.kingsrook.qqq.backend.core.context.QContext.getQBackendTransaction()).isNull();
}
/***************************************************************************
** Native MySQL session identity is independent of JDBC wrapper identity.
***************************************************************************/
private static long physicalId(Connection connection) throws Exception
{
try(var statement = connection.createStatement(); var rows = statement.executeQuery("SELECT CONNECTION_ID()"))
{
rows.next();
return (rows.getLong(1));
}
}
}