@serve.zone/dcrouter 2.12.4

package/test/suite/smtpclient_commands/test.ccmd-11.help-command.ts

@@ -0,0 +1,409 @@
+import { tap, expect } from '@git.zone/tstest/tapbundle';
+import { startTestServer, stopTestServer, type ITestServer } from '../../helpers/server.loader.js';
+import { createSmtpClient } from '../../../ts/mail/delivery/smtpclient/index.js';
+import type { SmtpClient } from '../../../ts/mail/delivery/smtpclient/smtp-client.js';
+import { Email } from '../../../ts/mail/core/classes.email.js';
+
+let testServer: ITestServer;
+let smtpClient: SmtpClient;
+
+tap.test('setup test SMTP server', async () => {
+  testServer = await startTestServer({
+    port: 2551,
+    tlsEnabled: false,
+    authRequired: false
+  });
+  expect(testServer).toBeTruthy();
+  expect(testServer.port).toBeGreaterThan(0);
+});
+
+tap.test('CCMD-11: Server capabilities discovery', async () => {
+  // Test server capabilities which is what HELP provides info about
+  smtpClient = createSmtpClient({
+    host: testServer.hostname,
+    port: testServer.port,
+    secure: false,
+    connectionTimeout: 5000
+  });
+  
+  console.log('Testing server capabilities discovery (HELP equivalent):\n');
+  
+  // Send a test email to see server capabilities in action
+  const testEmail = new Email({
+    from: 'sender@example.com',
+    to: ['recipient@example.com'],
+    subject: 'Capability test',
+    text: 'Testing server capabilities'
+  });
+  
+  await smtpClient.sendMail(testEmail);
+  console.log('Email sent successfully - server supports basic SMTP commands');
+  
+  // Test different configurations to understand server behavior
+  const capabilities = {
+    basicSMTP: true,
+    multiplRecipients: false,
+    largeMessages: false,
+    internationalDomains: false
+  };
+  
+  // Test multiple recipients
+  try {
+    const multiEmail = new Email({
+      from: 'sender@example.com',
+      to: ['recipient1@example.com', 'recipient2@example.com', 'recipient3@example.com'],
+      subject: 'Multi-recipient test',
+      text: 'Testing multiple recipients'
+    });
+    await smtpClient.sendMail(multiEmail);
+    capabilities.multiplRecipients = true;
+    console.log('✓ Server supports multiple recipients');
+  } catch (error) {
+    console.log('✗ Multiple recipients not supported');
+  }
+  
+  console.log('\nDetected capabilities:', capabilities);
+});
+
+tap.test('CCMD-11: Error message diagnostics', async () => {
+  // Test error messages which HELP would explain
+  console.log('Testing error message diagnostics:\n');
+  
+  const errorTests = [
+    {
+      description: 'Invalid sender address',
+      email: {
+        from: 'invalid-sender',
+        to: ['recipient@example.com'],
+        subject: 'Test',
+        text: 'Test'
+      }
+    },
+    {
+      description: 'Empty recipient list',
+      email: {
+        from: 'sender@example.com',
+        to: [],
+        subject: 'Test',
+        text: 'Test'
+      }
+    },
+    {
+      description: 'Null subject',
+      email: {
+        from: 'sender@example.com',
+        to: ['recipient@example.com'],
+        subject: null as any,
+        text: 'Test'
+      }
+    }
+  ];
+  
+  for (const test of errorTests) {
+    console.log(`Testing: ${test.description}`);
+    try {
+      const email = new Email(test.email);
+      await smtpClient.sendMail(email);
+      console.log('  Unexpectedly succeeded');
+    } catch (error) {
+      console.log(`  Error: ${error.message}`);
+      console.log(`  This would be explained in HELP documentation`);
+    }
+    console.log('');
+  }
+});
+
+tap.test('CCMD-11: Connection configuration help', async () => {
+  // Test different connection configurations
+  console.log('Testing connection configurations:\n');
+  
+  const configs = [
+    {
+      name: 'Standard connection',
+      config: {
+        host: testServer.hostname,
+        port: testServer.port,
+        secure: false,
+        connectionTimeout: 5000
+      },
+      shouldWork: true
+    },
+    {
+      name: 'With greeting timeout',
+      config: {
+        host: testServer.hostname,
+        port: testServer.port,
+        secure: false,
+        connectionTimeout: 5000,
+        greetingTimeout: 3000
+      },
+      shouldWork: true
+    },
+    {
+      name: 'With socket timeout',
+      config: {
+        host: testServer.hostname,
+        port: testServer.port,
+        secure: false,
+        connectionTimeout: 5000,
+        socketTimeout: 10000
+      },
+      shouldWork: true
+    }
+  ];
+  
+  for (const testConfig of configs) {
+    console.log(`Testing: ${testConfig.name}`);
+    try {
+      const client = createSmtpClient(testConfig.config);
+      const email = new Email({
+        from: 'sender@example.com',
+        to: ['recipient@example.com'],
+        subject: 'Config test',
+        text: `Testing ${testConfig.name}`
+      });
+      
+      await client.sendMail(email);
+      console.log(`  ✓ Configuration works`);
+    } catch (error) {
+      console.log(`  ✗ Error: ${error.message}`);
+    }
+  }
+});
+
+tap.test('CCMD-11: Protocol flow documentation', async () => {
+  // Document the protocol flow (what HELP would explain)
+  console.log('SMTP Protocol Flow (as HELP would document):\n');
+  
+  const protocolSteps = [
+    '1. Connection established',
+    '2. Server sends greeting (220)',
+    '3. Client sends EHLO',
+    '4. Server responds with capabilities',
+    '5. Client sends MAIL FROM',
+    '6. Server accepts sender (250)',
+    '7. Client sends RCPT TO',
+    '8. Server accepts recipient (250)',
+    '9. Client sends DATA',
+    '10. Server ready for data (354)',
+    '11. Client sends message content',
+    '12. Client sends . to end',
+    '13. Server accepts message (250)',
+    '14. Client can send more or QUIT'
+  ];
+  
+  console.log('Standard SMTP transaction flow:');
+  protocolSteps.forEach(step => console.log(`  ${step}`));
+  
+  // Demonstrate the flow
+  console.log('\nDemonstrating flow with actual email:');
+  const email = new Email({
+    from: 'demo@example.com',
+    to: ['recipient@example.com'],
+    subject: 'Protocol flow demo',
+    text: 'Demonstrating SMTP protocol flow'
+  });
+  
+  await smtpClient.sendMail(email);
+  console.log('✓ Protocol flow completed successfully');
+});
+
+tap.test('CCMD-11: Command availability matrix', async () => {
+  // Test what commands are available (HELP info)
+  console.log('Testing command availability:\n');
+  
+  // Test various email features to determine support
+  const features = {
+    plainText: { supported: false, description: 'Plain text emails' },
+    htmlContent: { supported: false, description: 'HTML emails' },
+    attachments: { supported: false, description: 'File attachments' },
+    multipleRecipients: { supported: false, description: 'Multiple recipients' },
+    ccRecipients: { supported: false, description: 'CC recipients' },
+    bccRecipients: { supported: false, description: 'BCC recipients' },
+    customHeaders: { supported: false, description: 'Custom headers' },
+    priorities: { supported: false, description: 'Email priorities' }
+  };
+  
+  // Test plain text
+  try {
+    await smtpClient.sendMail(new Email({
+      from: 'sender@example.com',
+      to: ['recipient@example.com'],
+      subject: 'Plain text test',
+      text: 'Plain text content'
+    }));
+    features.plainText.supported = true;
+  } catch (e) {}
+  
+  // Test HTML
+  try {
+    await smtpClient.sendMail(new Email({
+      from: 'sender@example.com',
+      to: ['recipient@example.com'],
+      subject: 'HTML test',
+      html: '<p>HTML content</p>'
+    }));
+    features.htmlContent.supported = true;
+  } catch (e) {}
+  
+  // Test multiple recipients
+  try {
+    await smtpClient.sendMail(new Email({
+      from: 'sender@example.com',
+      to: ['recipient1@example.com', 'recipient2@example.com'],
+      subject: 'Multiple recipients test',
+      text: 'Test'
+    }));
+    features.multipleRecipients.supported = true;
+  } catch (e) {}
+  
+  // Test CC
+  try {
+    await smtpClient.sendMail(new Email({
+      from: 'sender@example.com',
+      to: ['recipient@example.com'],
+      cc: ['cc@example.com'],
+      subject: 'CC test',
+      text: 'Test'
+    }));
+    features.ccRecipients.supported = true;
+  } catch (e) {}
+  
+  // Test BCC
+  try {
+    await smtpClient.sendMail(new Email({
+      from: 'sender@example.com',
+      to: ['recipient@example.com'],
+      bcc: ['bcc@example.com'],
+      subject: 'BCC test',
+      text: 'Test'
+    }));
+    features.bccRecipients.supported = true;
+  } catch (e) {}
+  
+  console.log('Feature support matrix:');
+  Object.entries(features).forEach(([key, value]) => {
+    console.log(`  ${value.description}: ${value.supported ? '✓ Supported' : '✗ Not supported'}`);
+  });
+});
+
+tap.test('CCMD-11: Error code reference', async () => {
+  // Document error codes (HELP would explain these)
+  console.log('SMTP Error Code Reference (as HELP would provide):\n');
+  
+  const errorCodes = [
+    { code: '220', meaning: 'Service ready', type: 'Success' },
+    { code: '221', meaning: 'Service closing transmission channel', type: 'Success' },
+    { code: '250', meaning: 'Requested action completed', type: 'Success' },
+    { code: '251', meaning: 'User not local; will forward', type: 'Success' },
+    { code: '354', meaning: 'Start mail input', type: 'Intermediate' },
+    { code: '421', meaning: 'Service not available', type: 'Temporary failure' },
+    { code: '450', meaning: 'Mailbox unavailable', type: 'Temporary failure' },
+    { code: '451', meaning: 'Local error in processing', type: 'Temporary failure' },
+    { code: '452', meaning: 'Insufficient storage', type: 'Temporary failure' },
+    { code: '500', meaning: 'Syntax error', type: 'Permanent failure' },
+    { code: '501', meaning: 'Syntax error in parameters', type: 'Permanent failure' },
+    { code: '502', meaning: 'Command not implemented', type: 'Permanent failure' },
+    { code: '503', meaning: 'Bad sequence of commands', type: 'Permanent failure' },
+    { code: '550', meaning: 'Mailbox not found', type: 'Permanent failure' },
+    { code: '551', meaning: 'User not local', type: 'Permanent failure' },
+    { code: '552', meaning: 'Storage allocation exceeded', type: 'Permanent failure' },
+    { code: '553', meaning: 'Mailbox name not allowed', type: 'Permanent failure' },
+    { code: '554', meaning: 'Transaction failed', type: 'Permanent failure' }
+  ];
+  
+  console.log('Common SMTP response codes:');
+  errorCodes.forEach(({ code, meaning, type }) => {
+    console.log(`  ${code} - ${meaning} (${type})`);
+  });
+  
+  // Test triggering some errors
+  console.log('\nDemonstrating error handling:');
+  
+  // Invalid email format
+  try {
+    await smtpClient.sendMail(new Email({
+      from: 'invalid-email-format',
+      to: ['recipient@example.com'],
+      subject: 'Test',
+      text: 'Test'
+    }));
+  } catch (error) {
+    console.log(`Invalid format error: ${error.message}`);
+  }
+});
+
+tap.test('CCMD-11: Debugging assistance', async () => {
+  // Test debugging features (HELP assists with debugging)
+  console.log('Debugging assistance features:\n');
+  
+  // Create client with debug enabled
+  const debugClient = createSmtpClient({
+    host: testServer.hostname,
+    port: testServer.port,
+    secure: false,
+    connectionTimeout: 5000,
+    debug: true
+  });
+  
+  console.log('Sending email with debug mode enabled:');
+  console.log('(Debug output would show full SMTP conversation)\n');
+  
+  const debugEmail = new Email({
+    from: 'debug@example.com',
+    to: ['recipient@example.com'],
+    subject: 'Debug test',
+    text: 'Testing with debug mode'
+  });
+  
+  // The debug output will be visible in the console
+  await debugClient.sendMail(debugEmail);
+  
+  console.log('\nDebug mode helps troubleshoot:');
+  console.log('- Connection issues');
+  console.log('- Authentication problems');
+  console.log('- Message formatting errors');
+  console.log('- Server response codes');
+  console.log('- Protocol violations');
+});
+
+tap.test('CCMD-11: Performance benchmarks', async () => {
+  // Performance info (HELP might mention performance tips)
+  console.log('Performance benchmarks:\n');
+  
+  const messageCount = 10;
+  const startTime = Date.now();
+  
+  for (let i = 0; i < messageCount; i++) {
+    const email = new Email({
+      from: 'perf@example.com',
+      to: ['recipient@example.com'],
+      subject: `Performance test ${i + 1}`,
+      text: 'Testing performance'
+    });
+    
+    await smtpClient.sendMail(email);
+  }
+  
+  const totalTime = Date.now() - startTime;
+  const avgTime = totalTime / messageCount;
+  
+  console.log(`Sent ${messageCount} emails in ${totalTime}ms`);
+  console.log(`Average time per email: ${avgTime.toFixed(2)}ms`);
+  console.log(`Throughput: ${(1000 / avgTime).toFixed(2)} emails/second`);
+  
+  console.log('\nPerformance tips:');
+  console.log('- Use connection pooling for multiple emails');
+  console.log('- Enable pipelining when supported');
+  console.log('- Batch recipients when possible');
+  console.log('- Use appropriate timeouts');
+  console.log('- Monitor connection limits');
+});
+
+tap.test('cleanup test SMTP server', async () => {
+  if (testServer) {
+    await stopTestServer(testServer);
+  }
+});
+
+export default tap.start();

package/test/suite/smtpclient_connection/test.ccm-01.basic-tcp-connection.ts

@@ -0,0 +1,150 @@
+import { tap, expect } from '@git.zone/tstest/tapbundle';
+import { startTestServer, stopTestServer, type ITestServer } from '../../helpers/server.loader.js';
+import { createSmtpClient } from '../../../ts/mail/delivery/smtpclient/index.js';
+import type { SmtpClient } from '../../../ts/mail/delivery/smtpclient/smtp-client.js';
+
+let testServer: ITestServer;
+let smtpClient: SmtpClient;
+
+tap.test('setup - start SMTP server for basic connection test', async () => {
+  testServer = await startTestServer({
+    port: 2525,
+    tlsEnabled: false,
+    authRequired: false
+  });
+  
+  expect(testServer.port).toEqual(2525);
+});
+
+tap.test('CCM-01: Basic TCP Connection - should connect to SMTP server', async () => {
+  const startTime = Date.now();
+  
+  try {
+    // Create SMTP client
+    smtpClient = createSmtpClient({
+      host: testServer.hostname,
+      port: testServer.port,
+      secure: false,
+      connectionTimeout: 5000,
+      debug: true
+    });
+    
+    // Verify connection
+    const isConnected = await smtpClient.verify();
+    expect(isConnected).toBeTrue();
+    
+    const duration = Date.now() - startTime;
+    console.log(`✅ Basic TCP connection established in ${duration}ms`);
+    
+  } catch (error) {
+    const duration = Date.now() - startTime;
+    console.error(`❌ Basic TCP connection failed after ${duration}ms:`, error);
+    throw error;
+  }
+});
+
+tap.test('CCM-01: Basic TCP Connection - should report connection status', async () => {
+  // After verify(), connection is closed, so isConnected should be false
+  expect(smtpClient.isConnected()).toBeFalse();
+  
+  const poolStatus = smtpClient.getPoolStatus();
+  console.log('📊 Connection pool status:', poolStatus);
+  
+  // After verify(), pool should be empty
+  expect(poolStatus.total).toEqual(0);
+  expect(poolStatus.active).toEqual(0);
+  
+  // Test that connection status is correct during actual email send
+  const email = new (await import('../../../ts/mail/core/classes.email.js')).Email({
+    from: 'sender@example.com',
+    to: ['recipient@example.com'],
+    subject: 'Connection status test',
+    text: 'Testing connection status'
+  });
+  
+  // During sendMail, connection should be established
+  const sendPromise = smtpClient.sendMail(email);
+  
+  // Check status while sending (might be too fast to catch)
+  const duringStatus = smtpClient.getPoolStatus();
+  console.log('📊 Pool status during send:', duringStatus);
+  
+  await sendPromise;
+  
+  // After send, connection might be pooled or closed
+  const afterStatus = smtpClient.getPoolStatus();
+  console.log('📊 Pool status after send:', afterStatus);
+});
+
+tap.test('CCM-01: Basic TCP Connection - should handle multiple connect/disconnect cycles', async () => {
+  // Close existing connection
+  await smtpClient.close();
+  expect(smtpClient.isConnected()).toBeFalse();
+  
+  // Create new client and test reconnection
+  for (let i = 0; i < 3; i++) {
+    const cycleClient = createSmtpClient({
+      host: testServer.hostname,
+      port: testServer.port,
+      secure: false,
+      connectionTimeout: 5000
+    });
+    
+    const isConnected = await cycleClient.verify();
+    expect(isConnected).toBeTrue();
+    
+    await cycleClient.close();
+    expect(cycleClient.isConnected()).toBeFalse();
+    
+    console.log(`✅ Connection cycle ${i + 1} completed`);
+  }
+});
+
+tap.test('CCM-01: Basic TCP Connection - should fail with invalid host', async () => {
+  const invalidClient = createSmtpClient({
+    host: 'invalid.host.that.does.not.exist',
+    port: 2525,
+    secure: false,
+    connectionTimeout: 3000
+  });
+  
+  // verify() returns false on connection failure, doesn't throw
+  const result = await invalidClient.verify();
+  expect(result).toBeFalse();
+  console.log('✅ Correctly failed to connect to invalid host');
+  
+  await invalidClient.close();
+});
+
+tap.test('CCM-01: Basic TCP Connection - should timeout on unresponsive port', async () => {
+  const startTime = Date.now();
+  
+  const timeoutClient = createSmtpClient({
+    host: testServer.hostname,
+    port: 9999, // Port that's not listening
+    secure: false,
+    connectionTimeout: 2000
+  });
+  
+  // verify() returns false on connection failure, doesn't throw
+  const result = await timeoutClient.verify();
+  expect(result).toBeFalse();
+  
+  const duration = Date.now() - startTime;
+  expect(duration).toBeLessThan(3000); // Should timeout within 3 seconds
+  console.log(`✅ Connection timeout working correctly (${duration}ms)`);
+  
+  await timeoutClient.close();
+});
+
+tap.test('cleanup - close SMTP client', async () => {
+  if (smtpClient && smtpClient.isConnected()) {
+    await smtpClient.close();
+  }
+});
+
+tap.test('cleanup - stop SMTP server', async () => {
+  await stopTestServer(testServer);
+});
+
+export default tap.start();

package/test/suite/smtpclient_connection/test.ccm-02.tls-connection.ts

@@ -0,0 +1,140 @@
+import { tap, expect } from '@git.zone/tstest/tapbundle';
+import { startTestServer, stopTestServer, type ITestServer } from '../../helpers/server.loader.js';
+import { createSmtpClient } from '../../../ts/mail/delivery/smtpclient/index.js';
+import type { SmtpClient } from '../../../ts/mail/delivery/smtpclient/smtp-client.js';
+import { Email } from '../../../ts/mail/core/classes.email.js';
+
+let testServer: ITestServer;
+let smtpClient: SmtpClient;
+
+tap.test('setup - start SMTP server with TLS', async () => {
+  testServer = await startTestServer({
+    port: 2526,
+    tlsEnabled: true,
+    authRequired: false
+  });
+  
+  expect(testServer.port).toEqual(2526);
+  expect(testServer.config.tlsEnabled).toBeTrue();
+});
+
+tap.test('CCM-02: TLS Connection - should establish secure connection via STARTTLS', async () => {
+  const startTime = Date.now();
+  
+  try {
+    // Create SMTP client with STARTTLS (not direct TLS)
+    smtpClient = createSmtpClient({
+      host: testServer.hostname,
+      port: testServer.port,
+      secure: false, // Start with plain connection
+      connectionTimeout: 10000,
+      tls: {
+        rejectUnauthorized: false // For self-signed test certificates
+      },
+      debug: true
+    });
+    
+    // Verify connection (will upgrade to TLS via STARTTLS)
+    const isConnected = await smtpClient.verify();
+    expect(isConnected).toBeTrue();
+    
+    const duration = Date.now() - startTime;
+    console.log(`✅ STARTTLS connection established in ${duration}ms`);
+    
+  } catch (error) {
+    const duration = Date.now() - startTime;
+    console.error(`❌ STARTTLS connection failed after ${duration}ms:`, error);
+    throw error;
+  }
+});
+
+tap.test('CCM-02: TLS Connection - should send email over secure connection', async () => {
+  const email = new Email({
+    from: 'test@example.com',
+    to: 'recipient@example.com',
+    subject: 'TLS Connection Test',
+    text: 'This email was sent over a secure TLS connection',
+    html: '<p>This email was sent over a <strong>secure TLS connection</strong></p>'
+  });
+  
+  const result = await smtpClient.sendMail(email);
+  
+  expect(result).toBeTruthy();
+  expect(result.success).toBeTrue();
+  expect(result.messageId).toBeTruthy();
+  
+  console.log(`✅ Email sent over TLS with message ID: ${result.messageId}`);
+});
+
+tap.test('CCM-02: TLS Connection - should reject invalid certificates when required', async () => {
+  // Create new client with strict certificate validation
+  const strictClient = createSmtpClient({
+    host: testServer.hostname,
+    port: testServer.port,
+    secure: false,
+    tls: {
+      rejectUnauthorized: true // Strict validation
+    }
+  });
+  
+  // Should fail with self-signed certificate
+  const result = await strictClient.verify();
+  expect(result).toBeFalse();
+  
+  console.log('✅ Correctly rejected self-signed certificate with strict validation');
+  
+  await strictClient.close();
+});
+
+tap.test('CCM-02: TLS Connection - should work with direct TLS if supported', async () => {
+  // Try direct TLS connection (might fail if server doesn't support it)
+  const directTlsClient = createSmtpClient({
+    host: testServer.hostname,
+    port: testServer.port,
+    secure: true, // Direct TLS from start
+    connectionTimeout: 5000,
+    tls: {
+      rejectUnauthorized: false
+    }
+  });
+  
+  const result = await directTlsClient.verify();
+  
+  if (result) {
+    console.log('✅ Direct TLS connection supported and working');
+  } else {
+    console.log('ℹ️ Direct TLS not supported, STARTTLS is the way');
+  }
+  
+  await directTlsClient.close();
+});
+
+tap.test('CCM-02: TLS Connection - should verify TLS cipher suite', async () => {
+  // Send email and check connection details
+  const email = new Email({
+    from: 'cipher-test@example.com',
+    to: 'recipient@example.com',
+    subject: 'TLS Cipher Test',
+    text: 'Testing TLS cipher suite'
+  });
+  
+  // The actual cipher info would be in debug logs
+  console.log('ℹ️ TLS cipher information available in debug logs');
+  
+  const result = await smtpClient.sendMail(email);
+  expect(result.success).toBeTrue();
+  
+  console.log('✅ Email sent successfully over encrypted connection');
+});
+
+tap.test('cleanup - close SMTP client', async () => {
+  if (smtpClient) {
+    await smtpClient.close();
+  }
+});
+
+tap.test('cleanup - stop SMTP server', async () => {
+  await stopTestServer(testServer);
+});
+
+export default tap.start();