@volter/twin-gmail 0.0.0-stage → 1.0.0

package/src/semantics/states.ts

@@ -0,0 +1,41 @@
+// Gmail's receiving server's state machine (docs/contributing/architecture.md, "What an author writes": states): a
+// session's stage, each move cited from RFC 5321. The front (./around.ts) asks it for every command, so the declaration
+// is the rule. A receiving server asks no authentication, so a session has no AUTH stage.
+import type { StateField, Transition } from '@volter/world-core';
+
+const RFC5321 = (section: string, quote: string): string => `spec:${section} "${quote}"`;
+// Where the documentation stops: Gmail's words for a command out of order, recalled from its server's replies
+const badSequence = (message: string) => ({ status: 503, code: '5.5.1', message });
+
+const ORDER = 'Once started, a mail transaction consists of a transaction beginning command, one or more RCPT commands, and a DATA command, in that order.';
+
+// fresh (nothing yet), helo or ehlo (greeted), mail (a sender), rcpt (recipients), data (the message's lines), closed
+const stage: Transition[] = [
+  { operation: 'EHLO', from: '*', to: 'ehlo', source: RFC5321('4.1.4', 'If it is issued after the session begins and the EHLO command is acceptable to the SMTP server, the SMTP server MUST clear all buffers and reset the state exactly as if a RSET command had been issued.') },
+  { operation: 'HELO', from: '*', to: 'helo', source: RFC5321('4.1.1.1', 'These commands are used to identify the SMTP client to the SMTP server.') },
+  {
+    operation: 'MAIL', from: ['helo', 'ehlo'], to: 'mail',
+    refusals: { fresh: badSequence('EHLO/HELO first. - gsmtp'), mail: badSequence('Nested MAIL command. - gsmtp'), rcpt: badSequence('Nested MAIL command. - gsmtp') },
+    source: RFC5321('4.1.4', 'MAIL (or SEND, SOML, or SAML) MUST NOT be sent if a mail transaction is already open'),
+  },
+  {
+    operation: 'RCPT', from: ['mail', 'rcpt'], to: 'rcpt',
+    refusals: { fresh: badSequence('MAIL first. - gsmtp'), helo: badSequence('MAIL first. - gsmtp'), ehlo: badSequence('MAIL first. - gsmtp') },
+    source: RFC5321('4.1.4', ORDER),
+  },
+  {
+    operation: 'DATA', from: ['rcpt'], to: 'data',
+    refusals: { fresh: badSequence('MAIL first. - gsmtp'), helo: badSequence('MAIL first. - gsmtp'), ehlo: badSequence('MAIL first. - gsmtp'), mail: badSequence('RCPT first. - gsmtp') },
+    source: RFC5321('4.1.4', ORDER),
+  },
+  // the end-of-data dot closes the transaction, back to the greeting the session had
+  { operation: 'DATA', from: ['data'], to: 'ehlo', source: RFC5321('4.1.4', 'or if the previous one successfully concluded with a successful DATA command') },
+  { operation: 'DATA', from: ['data'], to: 'helo', source: RFC5321('4.1.4', 'or if the previous one successfully concluded with a successful DATA command') },
+  { operation: 'RSET', from: ['mail', 'rcpt'], to: 'ehlo', source: RFC5321('4.1.1.5', 'This command specifies that the current mail transaction will be aborted.') },
+  { operation: 'RSET', from: ['mail', 'rcpt'], to: 'helo', source: RFC5321('4.1.1.5', 'This command specifies that the current mail transaction will be aborted.') },
+  { operation: 'QUIT', from: '*', to: 'closed', source: RFC5321('4.1.1.10', 'The QUIT command may be issued at any time.') },
+];
+
+export const states: Record<string, { state: Record<string, StateField> }> = {
+  Session: { state: { stage: { initial: 'fresh', transitions: stage } } },
+};

package/src/server.ts

@@ -0,0 +1,19 @@
+// FETCH-FIRST (runtime contract R12b) with a wire of the pack's own: the webmail on the main port (the pack's fetch) and
+// Gmail's receiving SMTP server on its side port (`smtpPort`, the manifest's sidePorts: the kernel's `serveStream`
+// carrying the byte-stream door's connections), where the World's senders hand gmail.com's mail (ctx.mail). A listener
+// that fails to open releases the one already open; stop closes both and settles once both have.
+import { serveHttp, serveStream, type PackFetchOptions } from '@volter/world-core';
+import { createGmailFetch } from './fetch.ts';
+import { createGmailTwinStream } from './stream.ts';
+
+export async function createGmailTwinServer(options: PackFetchOptions & { port?: number; smtpPort?: number } = {}): Promise<{ port: number; smtpPort: number; stop: () => Promise<void> }> {
+  const server = await serveHttp({ port: options.port ?? 0, idleTimeout: 60, fetch: createGmailFetch(options) });
+  let smtp: Awaited<ReturnType<typeof serveStream>>;
+  try { smtp = await serveStream({ port: options.smtpPort ?? 0, stream: createGmailTwinStream(options) }); }
+  catch (error) { await server.stop(true); throw error; }
+  return {
+    port: server.port ?? options.port ?? 0,
+    smtpPort: smtp.port,
+    stop: async () => { await Promise.all([smtp.stop(), server.stop(true)]); },
+  };
+}

package/src/stream.ts

@@ -0,0 +1,11 @@
+// GMAIL'S RECEIVING SERVER'S BYTE-STREAM DOOR (world-core's TwinStream): a connection's bytes framed and carried to the
+// server's front (./semantics/around.ts) by the kernel's SMTP server machine (`smtpServer.smtpStream`, RFC 5321
+// §4.1.1.4 and §4.5.2). The host carries the bytes: a local listener's socket on the pack's SMTP side port (./server.ts),
+// or the World's sender in process (a journey walk's companion).
+import { smtpServer, type PackFetchOptions, type TwinStream } from '@volter/world-core';
+import { createGmailFetch } from './fetch.ts';
+import { BRIDGE } from './semantics/shared.ts';
+
+export function createGmailTwinStream(options: PackFetchOptions = {}): TwinStream {
+  return smtpServer.smtpStream(createGmailFetch(options), BRIDGE);
+}