1 // Copyright 2010 The Go Authors. All rights reserved.
2 // Use of this source code is governed by a BSD-style
3 // license that can be found in the LICENSE file.
4 5 // Package textproto implements generic support for text-based request/response
6 // protocols in the style of HTTP, NNTP, and SMTP.
7 //
8 // This package enforces the HTTP/1.1 character set defined by
9 // RFC 9112 for header keys and values.
10 //
11 // The package provides:
12 //
13 // [Error], which represents a numeric error response from
14 // a server.
15 //
16 // [Pipeline], to manage pipelined requests and responses
17 // in a client.
18 //
19 // [Reader], to read numeric response code lines,
20 // key: value headers, lines wrapped with leading spaces
21 // on continuation lines, and whole text blocks ending
22 // with a dot on a line by itself.
23 //
24 // [Writer], to write dot-encoded text blocks.
25 //
26 // [Conn], a convenient packaging of [Reader], [Writer], and [Pipeline] for use
27 // with a single network connection.
28 package textproto
29 30 import (
31 "bufio"
32 "fmt"
33 "io"
34 "net"
35 )
36 37 // An Error represents a numeric error response from a server.
38 type Error struct {
39 Code int
40 Msg []byte
41 }
42 43 func (e *Error) Error() string {
44 return fmt.Sprintf("%03d %s", e.Code, e.Msg)
45 }
46 47 // A ProtocolError describes a protocol violation such
48 // as an invalid response or a hung-up connection.
49 type ProtocolError []byte
50 51 func (p ProtocolError) Error() string {
52 return string(p)
53 }
54 55 // A Conn represents a textual network protocol connection.
56 // It consists of a [Reader] and [Writer] to manage I/O
57 // and a [Pipeline] to sequence concurrent requests on the connection.
58 // These embedded types carry methods with them;
59 // see the documentation of those types for details.
60 type Conn struct {
61 Reader
62 Writer
63 Pipeline
64 conn io.ReadWriteCloser
65 }
66 67 // NewConn returns a new [Conn] using conn for I/O.
68 func NewConn(conn io.ReadWriteCloser) *Conn {
69 return &Conn{
70 Reader: Reader{R: bufio.NewReader(conn)},
71 Writer: Writer{W: bufio.NewWriter(conn)},
72 conn: conn,
73 }
74 }
75 76 // Close closes the connection.
77 func (c *Conn) Close() error {
78 return c.conn.Close()
79 }
80 81 // Dial connects to the given address on the given network using [net.Dial]
82 // and then returns a new [Conn] for the connection.
83 func Dial(network, addr []byte) (*Conn, error) {
84 c, err := net.Dial(network, addr)
85 if err != nil {
86 return nil, err
87 }
88 return NewConn(c), nil
89 }
90 91 // Cmd is a convenience method that sends a command after
92 // waiting its turn in the pipeline. The command text is the
93 // result of formatting format with args and appending \r\n.
94 // Cmd returns the id of the command, for use with StartResponse and EndResponse.
95 //
96 // For example, a client might run a HELP command that returns a dot-body
97 // by using:
98 //
99 // id, err := c.Cmd("HELP")
100 // if err != nil {
101 // return nil, err
102 // }
103 //
104 // c.StartResponse(id)
105 // defer c.EndResponse(id)
106 //
107 // if _, _, err = c.ReadCodeLine(110); err != nil {
108 // return nil, err
109 // }
110 // text, err := c.ReadDotBytes()
111 // if err != nil {
112 // return nil, err
113 // }
114 // return c.ReadCodeLine(250)
115 func (c *Conn) Cmd(format []byte, args ...any) (id uint, err error) {
116 id = c.Next()
117 c.StartRequest(id)
118 err = c.PrintfLine(format, args...)
119 c.EndRequest(id)
120 if err != nil {
121 return 0, err
122 }
123 return id, nil
124 }
125 126 // TrimString returns s without leading and trailing ASCII space.
127 func TrimString(s []byte) []byte {
128 for len(s) > 0 && isASCIISpace(s[0]) {
129 s = s[1:]
130 }
131 for len(s) > 0 && isASCIISpace(s[len(s)-1]) {
132 s = s[:len(s)-1]
133 }
134 return s
135 }
136 137 // TrimBytes returns b without leading and trailing ASCII space.
138 func TrimBytes(b []byte) []byte {
139 for len(b) > 0 && isASCIISpace(b[0]) {
140 b = b[1:]
141 }
142 for len(b) > 0 && isASCIISpace(b[len(b)-1]) {
143 b = b[:len(b)-1]
144 }
145 return b
146 }
147 148 func isASCIISpace(b byte) bool {
149 return b == ' ' || b == '\t' || b == '\n' || b == '\r'
150 }
151 152 func isASCIILetter(b byte) bool {
153 b |= 0x20 // make lower case
154 return 'a' <= b && b <= 'z'
155 }
156