ident

5.6 KB

1. # `hl:smtp` — sending mail
3. An SMTP **submission client**. Server realm. Mission 137.
5. ```hybriel
6. import { Mailer } from 'hl:smtp'
8. m = new Mailer("mail.example.com", 587, {
9. user = "[email protected]"
10. pass = "…"
11. "from" = "[email protected]"
12. })
14. m.send({ to = "[email protected]"; subject = "Hello"; text = "Hi there" })
16. for (r of m.results()) {
17. console.log(r.ok + " " + r.code + " " + r.message)
18. }
19. ```
21. ## `new Mailer(host, port, options)`
23. `host` / `port` / `options` are the first three declared properties, so the
24. positional form above reads as written (SPEC.md "The file root is the
25. constructor").
27. | option | default | meaning |
28. |---|---|---|
29. | `"from"` / `sender` | — | the envelope sender and the `From:` header. A mailer without one constructs; a `send()` whose message names no sender either is refused at that call. |
30. | `user` / `pass` | — | credentials; absent = no AUTH at all |
31. | `tls` | `"starttls"` | `"starttls"` · `"implicit"` (SMTPS, port 465) · `"none"` |
32. | `auth` | `"auto"` | `"auto"` (PLAIN unless only LOGIN is offered) · `"plain"` · `"login"` · `"none"` |
33. | `caFile` | — | an EXTRA trust anchor beside the system store — a private CA, or a test fixture's certificate |
34. | `verify` | `true` | peer chain + hostname. `false` is an explicit opt-out and is logged at every handshake |
35. | `allowInsecureAuth` | `false` | permit AUTH on a connection that never became TLS |
36. | `timeout` | `30000` | milliseconds, bounding the connect and every read/write |
37. | `helo` | `"localhost"` | the EHLO name and the `Message-ID` domain |
39. **`from` is a reserved word** in Hybriel (`import X from './x.hl'`), so the key
40. is written quoted — `"from" = …`. `sender` is the same field under a bare
41. identifier; use whichever reads better.
43. ## `m.send(message)` — non-blocking
45. | key | meaning |
46. |---|---|
47. | `to` | one address, or a list of them — ONE message, several `RCPT TO` |
48. | `subject` | ASCII passes through; anything else becomes an RFC 2047 encoded-word |
49. | `text` | the `text/plain` part |
50. | `html` | the `text/html` part; with both, a `multipart/alternative` body |
51. | `"from"` / `sender` | overrides the mailer's sender for this message |
53. Returns a **job id**. The conversation runs on the mailer's own worker thread
54. and the answer arrives later.
56. Everything that can fail LOCALLY is decided before the job leaves — on the
57. caller's thread, so it is a **located error at the caller's line**, catchable via
58. `on Error(e)` like any other plugin failure:
60. * a CR or LF in `to`, `"from"` or `subject` — **header injection is refused, never
61. stripped and never escaped.** `subject = "hi\r\nBcc: everyone@…"` is how a
62. contact form becomes an open relay; silently dropping the bytes would deliver a
63. message the author did not write.
64. * an address carrying `<`, `>` or whitespace, or no `@` at all
65. * an empty recipient list, a message with neither `text` nor `html`
67. ## The result
69. `m.results()` is the mailer's ONE result source. Drain it (`for (r of
70. m.results())`, which ENDS when every accepted send has been answered — that is
71. what lets a mail-only script terminate), or hand it to the event loop with
72. `m.deliver()` and handle `on m.sent(r)` / `on m.failed(r)`. Use one or the other:
73. they take from the same queue, and asking for both is a refusal.
75. ```
76. { id, ok, code, stage, message, secure, to }
77. ```
79. `stage` names the step that answered: `connect`, `greeting`, `ehlo`, `starttls`,
80. `auth`, `mail`, `rcpt`, `data`, `body`, `done`. `secure` says whether the message
81. was written inside TLS. A server's own refusal text arrives in `message`
82. verbatim.
84. `m.pending()` is how many sends have not been answered; `m.close()` stops the
85. worker (a job already in conversation finishes — abandoning a socket between
86. `DATA` and its `250` is how a message gets delivered twice).
88. ## What it does on the wire
90. `EHLO` · optional `STARTTLS` + a re-issued `EHLO` inside TLS (RFC 3207 §4.2 —
91. capabilities learned in the clear are discarded) · `AUTH PLAIN` (RFC 4616) or
92. `AUTH LOGIN` · `MAIL FROM` · one `RCPT TO` per recipient (a rejected recipient
93. fails the whole send) · `DATA` · the message · `QUIT`.
95. CRLF discipline and **dot-stuffing** (RFC 5321 §4.5.2) are applied to the whole
96. payload: a body line beginning with `.` is sent as `..`, or it truncates the
97. mail. Headers written: `From`, `To`, `Subject`, `Date`, `Message-ID`,
98. `MIME-Version`, `Content-Type`, `Content-Transfer-Encoding: 8bit`.
100. ## TLS
102. There is **no TLS implementation in this plugin.** It calls the client half of
103. `plugins/http/tls_common.zig` — the same dlopen'd OpenSSL the HTTP servers use
104. (mission 121, extended in 137). `native/test_smtp.sh` carries the grep gate that
105. keeps it that way.
107. ## Not in scope
109. * **Receiving** (IMAP/POP) — a different protocol and a different plugin.
110. * **DKIM signing** — later. It needs a key store and a canonicalisation pass over
111. the rendered message; the rendering seam is `renderMessage` in `smtp.zig` and
112. the signature would be one more header written there.
113. * **Queuing and retry** — the app's business. A `4xx` result is a retryable one
114. and the app knows what its retry policy is; a library that retried on its own
115. would send twice the moment the app also did.
116. * **`cc` / `bcc` headers, attachments** — not written. Extra recipients go in
117. `to`; an attachment needs a `multipart/mixed` builder that does not exist yet.
119. ## Tests
121. `bash native/test_smtp.sh` (61 checks). The only peer is
122. `tests/native/plugins/045_smtp_fixture.js`, a local fixture that asserts the
123. exact wire; **no test in this repo ever contacts a real mail server.** Ports come
124. from `HL_SMTP_PORT_BASE` (default 14700) and the harness moves itself rather than
125. touching a listener it did not start.