1package message_test
2
3import (
4 "bytes"
5 "errors"
6 "fmt"
7 "io"
8 "log"
9 "log/slog"
10 "strings"
11 "time"
12
13 "github.com/mjl-/mox/dns"
14 "github.com/mjl-/mox/message"
15 "github.com/mjl-/mox/smtp"
16)
17
18func ExampleDecodeReader() {
19 // Convert from iso-8859-1 to utf-8.
20 input := []byte{'t', 0xe9, 's', 't'}
21 output, err := io.ReadAll(message.DecodeReader("iso-8859-1", bytes.NewReader(input)))
22 if err != nil {
23 log.Fatalf("read from decoder: %v", err)
24 }
25 fmt.Printf("%s\n", string(output))
26 // Output: tést
27}
28
29func ExampleMessageIDCanonical() {
30 // Valid message-id.
31 msgid, invalidAddress, err := message.MessageIDCanonical("<ok@localhost>")
32 if err != nil {
33 fmt.Printf("invalid message-id: %v\n", err)
34 } else {
35 fmt.Printf("canonical: %s %v\n", msgid, invalidAddress)
36 }
37
38 // Missing <>.
39 msgid, invalidAddress, err = message.MessageIDCanonical("bogus@localhost")
40 if err != nil {
41 fmt.Printf("invalid message-id: %v\n", err)
42 } else {
43 fmt.Printf("canonical: %s %v\n", msgid, invalidAddress)
44 }
45
46 // Invalid address, but returned as not being in error.
47 msgid, invalidAddress, err = message.MessageIDCanonical("<invalid>")
48 if err != nil {
49 fmt.Printf("invalid message-id: %v\n", err)
50 } else {
51 fmt.Printf("canonical: %s %v\n", msgid, invalidAddress)
52 }
53
54 // Output:
55 // canonical: ok@localhost false
56 // invalid message-id: not a message-id: missing <
57 // canonical: invalid true
58}
59
60func ExampleThreadSubject() {
61 // Basic subject.
62 s, isResp := message.ThreadSubject("nothing special", false)
63 fmt.Printf("%s, response: %v\n", s, isResp)
64
65 // List tags and "re:" are stripped.
66 s, isResp = message.ThreadSubject("[list1] [list2] Re: test", false)
67 fmt.Printf("%s, response: %v\n", s, isResp)
68
69 // "fwd:" is stripped.
70 s, isResp = message.ThreadSubject("fwd: a forward", false)
71 fmt.Printf("%s, response: %v\n", s, isResp)
72
73 // Trailing "(fwd)" is also a forward.
74 s, isResp = message.ThreadSubject("another forward (fwd)", false)
75 fmt.Printf("%s, response: %v\n", s, isResp)
76
77 // [fwd: ...] is stripped.
78 s, isResp = message.ThreadSubject("[fwd: [list] fwd: re: it's complicated]", false)
79 fmt.Printf("%s, response: %v\n", s, isResp)
80
81 // Output:
82 // nothing special, response: false
83 // test, response: true
84 // a forward, response: true
85 // another forward, response: true
86 // it's complicated, response: true
87}
88
89func ExampleComposer() {
90 // We store in a buffer. We could also write to a file.
91 var b bytes.Buffer
92
93 // NewComposer. Keep in mind that operations on a Composer will panic on error.
94 xc := message.NewComposer(&b, 10*1024*1024)
95
96 // Catch and handle errors when composing.
97 defer func() {
98 x := recover()
99 if x == nil {
100 return
101 }
102 if err, ok := x.(error); ok && errors.Is(err, message.ErrCompose) {
103 log.Printf("compose: %v", err)
104 }
105 panic(x)
106 }()
107
108 // Add an address header.
109 xc.HeaderAddrs("From", []message.NameAddress{{DisplayName: "Charlie", Address: smtp.Address{Localpart: "root", Domain: dns.Domain{ASCII: "localhost"}}}})
110
111 // Add subject header, with encoding
112 xc.Subject("hi ☺")
113
114 // Add Date and Message-ID headers, required.
115 tm, _ := time.Parse(time.RFC3339, "2006-01-02T15:04:05+07:00")
116 xc.Header("Date", tm.Format(message.RFC5322Z))
117 xc.Header("Message-ID", "<unique@host>") // Should generate unique id for each message.
118
119 xc.Header("MIME-Version", "1.0")
120
121 // Write content-* headers for the text body.
122 body, ct, cte := xc.TextPart("this is the body")
123 xc.Header("Content-Type", ct)
124 xc.Header("Content-Transfer-Encoding", cte)
125
126 // Header/Body separator
127 xc.Line()
128
129 // The part body. Use mime/multipart to make messages with multiple parts.
130 xc.Write(body)
131
132 // Flush any buffered writes to the original writer.
133 xc.Flush()
134
135 fmt.Println(strings.ReplaceAll(b.String(), "\r\n", "\n"))
136 // Output:
137 // From: "Charlie" <root@localhost>
138 // Subject: hi =?utf-8?q?=E2=98=BA?=
139 // Date: 2 Jan 2006 15:04:05 +0700
140 // Message-ID: <unique@host>
141 // MIME-Version: 1.0
142 // Content-Type: text/plain; charset=us-ascii
143 // Content-Transfer-Encoding: 7bit
144 //
145 // this is the body
146}
147
148func ExamplePart() {
149 // Parse a message from an io.ReaderAt, which could be a file.
150 strict := false
151 r := strings.NewReader("header: value\r\nanother: value\r\n\r\nbody ...\r\n")
152 part, err := message.Parse(slog.Default(), strict, r)
153 if err != nil {
154 log.Fatalf("parsing message: %v", err)
155 }
156
157 // The headers of the first part have been parsed, i.e. the message headers.
158 // A message can be multipart (e.g. alternative, related, mixed), and possibly
159 // nested.
160
161 // By walking the entire message, all part metadata (like offsets into the file
162 // where a part starts) is recorded.
163 err = part.Walk(slog.Default(), nil)
164 if err != nil {
165 log.Fatalf("walking message: %v", err)
166 }
167
168 // Messages can have a recursive multipart structure. Print the structure.
169 var printPart func(indent string, p message.Part)
170 printPart = func(indent string, p message.Part) {
171 log.Printf("%s- part: %v", indent, part)
172 for _, pp := range p.Parts {
173 printPart(" "+indent, pp)
174 }
175 }
176 printPart("", part)
177}
178
179func ExampleWriter() {
180 // NewWriter on a string builder.
181 var b strings.Builder
182 w := message.NewWriter(&b)
183
184 // Write some lines, some with proper CRLF line ending, others without.
185 fmt.Fprint(w, "header: value\r\n")
186 fmt.Fprint(w, "another: value\n") // missing \r
187 fmt.Fprint(w, "\r\n")
188 fmt.Fprint(w, "hi ☺\n") // missing \r
189
190 fmt.Printf("%q\n", b.String())
191 fmt.Printf("%v %v", w.HaveBody, w.Has8bit)
192 // Output:
193 // "header: value\r\nanother: value\r\n\r\nhi ☺\r\n"
194 // true true
195}
196