Пакет textproto
Обзор
Пакет textproto реализует общую поддержку текстовых протоколов запросов/ответов в стиле HTTP, NNTP и SMTP.
Пакет предоставляет:
Ошибка, представляющую собой числовой ответ об ошибке от сервера.
Поток, для управления запросами и ответами в режиме "pipeline" в клиенте.
Чтец, для чтения строк с числовыми кодами ответов, заголовков вида «ключ: значение», строк с отступами в начале строк продолжения и целых текстовых блоков, заканчивающихся точкой на отдельной строке.
Писатель, для записи текстовых блоков в формате с точками.
Conn, удобная упаковка Reader, Writer и Pipeline для использования с одним сетевым соединением.
Индекс
Файлы пакета
header.go pipeline.go reader.go textproto.go writer.go
func CanonicalMIMEHeaderKey
func CanonicalMIMEHeaderKey(s string) string
CanonicalMIMEHeaderKey возвращает канонический формат имени MIME-заголовка s. Канонизация преобразует первую букву и любую букву после дефиса в верхний регистр; остальные преобразуются в нижний регистр. Например, каноническое имя для «accept-encoding» — «Accept-Encoding». Имена MIME-заголовков предполагаются только ASCII. Если s содержит пробел или недопустимые байты поля заголовка, он возвращается без изменений.
func TrimBytes 1.1
func TrimBytes(b []byte) []byte
TrimBytes возвращает b без начальных и конечных ASCII-пробелов.
func TrimString 1.1
func TrimString(s string) string
TrimString возвращает s без начальных и конечных ASCII-пробелов.
тип Conn
Conn представляет собой текстовое сетевое соединение протокола. Он состоит из Reader и Writer для управления вводом/выводом и Pipeline для упорядочивания одновременных запросов по соединению. Эти встроенные типы содержат методы; см. документацию этих типов для получения подробностей.
type Conn struct {
Reader
Writer
Pipeline
// contains filtered or unexported fields
}
func Dial
func Dial(network, addr string) (*Conn, error)
Dial подключается к заданному адресу по заданной сети с помощью net.Dial и затем возвращает новый Conn для подключения.
func NewConn
func NewConn(conn io.ReadWriteCloser) *Conn
NewConn возвращает новый Conn, используя conn для ввода/вывода.
func (*Conn) Close
func (c *Conn) Close() error
Close закрывает соединение.
func (*Conn) Cmd
func (c *Conn) Cmd(format string, args ...any) (id uint, err error)
Cmd — это удобный метод, который отправляет команду после ожидания своей очереди в потоке. Текст команды является результатом форматирования format с помощью args и добавления \r\n. Cmd возвращает id команды для использования с StartResponse и EndResponse.
Например, клиент может выполнить команду HELP, которая возвращает dot-body, используя:
id, err := c.Cmd("HELP")
if err != nil {
return nil, err
}
c.StartResponse(id)
defer c.EndResponse(id)
if _, _, err = c.ReadCodeLine(110); err != nil {
return nil, err
}
text, err := c.ReadDotBytes()
if err != nil {
return nil, err
}
return c.ReadCodeLine(250)
тип Error
Ошибка представляет собой числовой ответ об ошибке от сервера.
type Error struct {
Code int
Msg string
}
func (*Error) Error
func (e *Error) Error() string
тип MIMEHeader
MIMEHeader представляет собой карту MIME-стиля, сопоставляющую ключи с наборами значений.
type MIMEHeader map[string][]string
func (MIMEHeader) Add
func (h MIMEHeader) Add(key, value string)
Add добавляет пару ключ-значение в заголовок. Он добавляет в конец любые существующие значения, связанные с ключом.
func (MIMEHeader) Del
func (h MIMEHeader) Del(key string)
Del удаляет значения, связанные с ключом.
func (MIMEHeader) Get
func (h MIMEHeader) Get(key string) string
Get получает первое значение, связанное с данным ключом. Он нечувствителен к регистру; используется CanonicalMIMEHeaderKey для канонизации предоставленного ключа. Если связанных значений нет, Get возвращает "". Чтобы использовать неканонические ключи, обратитесь непосредственно к карте.
func (MIMEHeader) Set
func (h MIMEHeader) Set(key, value string)
Set устанавливает элементы заголовка, связанные с ключом, на единственное значение. Он заменяет любые существующие значения, связанные с ключом.
func (MIMEHeader) Values 1.14
func (h MIMEHeader) Values(key string) []string
Values возвращает все значения, связанные с данным ключом. Он нечувствителен к регистру; используется CanonicalMIMEHeaderKey для канонизации предоставленного ключа. Чтобы использовать неканонические ключи, обратитесь непосредственно к карте. Возвращаемый срез не является копией.
тип Pipeline
Pipeline управляет упорядоченной последовательностью запросов/ответов в режиме "pipeline".
Для использования Pipeline p для управления несколькими клиентами по соединению, каждый клиент должен выполнить:
id := p.Next() // take a number p.StartRequest(id) // wait for turn to send request «send request» p.EndRequest(id) // notify Pipeline that request is sent p.StartResponse(id) // wait for turn to read response «read response» p.EndResponse(id) // notify Pipeline that response is read
Пipelined сервер может использовать те же вызовы, чтобы убедиться, что ответы, вычисленные параллельно, записываются в правильном порядке.
type Pipeline struct {
// contains filtered or unexported fields
}
func (*Pipeline) EndRequest
func (p *Pipeline) EndRequest(id uint)
EndRequest сообщает p, что запрос с заданным id был отправлен (или, если это сервер, получен).
func (*Pipeline) EndResponse
func (p *Pipeline) EndResponse(id uint)
EndResponse сообщает p, что ответ с заданным id был получен (или, если это сервер, отправлен).
func (*Pipeline) Next
func (p *Pipeline) Next() uint
Next возвращает следующий id для пары запрос/ответ.
func (*Pipeline) StartRequest
func (p *Pipeline) StartRequest(id uint)
StartRequest блокирует выполнение, пока не придёт время отправить (или, если это сервер, получить) запрос с заданным id.
func (*Pipeline) StartResponse
func (p *Pipeline) StartResponse(id uint)
StartResponse блокирует выполнение, пока не придёт время получить (или, если это сервер, отправить) запрос с заданным id.
тип ProtocolError
ProtocolError описывает нарушение протокола, например, недействительный ответ или обрыв соединения.
type ProtocolError string
func (ProtocolError) Error
func (p ProtocolError) Error() string
тип Reader
Reader реализует удобные методы для чтения запросов или ответов из текстового сетевого соединения протокола.
type Reader struct {
R *bufio.Reader
// contains filtered or unexported fields
}
func NewReader
func NewReader(r *bufio.Reader) *Reader
NewReader возвращает новый Reader, читающий из r.
Для предотвращения атак типа "отказ в обслуживании", предоставленный bufio.Reader должен читать из io.LimitReader или аналогичного Reader, чтобы ограничить размер ответов.
func (*Reader) DotReader
func (r *Reader) DotReader() io.Reader
DotReader возвращает новый Reader, который удовлетворяет методам Reads, используя декодированный текст блока в формате с точкой, считанного из r. Возвращаемый Reader действителен только до следующего вызова метода r.
Dot-кодирование — это общее форматирование, используемое для блоков данных в текстовых протоколах, таких как SMTP. Данные состоят из последовательности строк, каждая из которых заканчивается "\r\n". Сама последовательность заканчивается строкой, содержащей только точку: ".\r\n". Строки, начинающиеся с точки, экранируются дополнительной точкой, чтобы избежать совпадения с концом последовательности.
Декодированная форма, возвращаемая методом Read Reader, переписывает "\r\n" окончания строк в более простые "\n", удаляет экранированные точки, если они присутствуют, и останавливается с ошибкой io.EOF после обработки (и отбрасывания) строки конца последовательности.
func (*Reader) ReadCodeLine
func (r *Reader) ReadCodeLine(expectCode int) (code int, message string, err error)
ReadCodeLine считывает строку кода ответа в формате
code message
где code — трёхзначный код состояния, а сообщение расширяется до остальной части строки. Пример такой строки:
220 plan9.bell-labs.com ESMTP
Если префикс статуса не совпадает с цифрами в expectCode, ReadCodeLine возвращает ошибку с err, установленным в &Error{code, message}. Например, если expectCode равен 31, ошибка будет возвращена, если статус не находится в диапазоне [310,319].
Если ответ состоит из нескольких строк, ReadCodeLine возвращает ошибку.
expectCode <= 0 отключает проверку кода состояния.
func (*Reader) ReadContinuedLine
func (r *Reader) ReadContinuedLine() (string, error)
ReadContinuedLine считывает, возможно, продолженную строку из r, удаляя конечные пробелы ASCII. Строки после первой считаются продолжениями, если они начинаются с пробела или табуляции. В возвращаемых данных строки продолжения отделяются от предыдущей строки только одним пробелом: перевод строки и начальные пробелы удаляются.
Например, рассмотрим такой ввод:
Line 1 continued... Line 2
Первый вызов ReadContinuedLine вернёт "Line 1 continued..." , а второй - "Line 2".
Пустые строки никогда не продолжаются.
func (*Reader) ReadContinuedLineBytes
func (r *Reader) ReadContinuedLineBytes() ([]byte, error)
ReadContinuedLineBytes аналогичен Reader.ReadContinuedLine, но возвращает []byte вместо строки.
func (*Reader) ReadDotBytes
func (r *Reader) ReadDotBytes() ([]byte, error)
ReadDotBytes считывает кодировку точек и возвращает декодированные данные.
См. документацию для метода Reader.DotReader для получения подробной информации о кодировке точек.
func (*Reader) ReadDotLines
func (r *Reader) ReadDotLines() ([]string, error)
ReadDotLines считывает кодировку точек и возвращает срез, содержащий декодированные строки, с удалёнными конечными \r\n или \n из каждой.
См. документацию для метода Reader.DotReader для получения подробной информации о кодировке точек.
func (*Reader) ReadLine
func (r *Reader) ReadLine() (string, error)
ReadLine считывает одну строку из r, удаляя конечные \n или \r\n из возвращаемой строки.
func (*Reader) ReadLineBytes
func (r *Reader) ReadLineBytes() ([]byte, error)
ReadLineBytes аналогичен Reader.ReadLine, но возвращает []byte вместо строки.
func (*Reader) ReadMIMEHeader
func (r *Reader) ReadMIMEHeader() (MIMEHeader, error)
ReadMIMEHeader считывает заголовок в стиле MIME из r. Заголовок представляет собой последовательность, возможно, продолженных строк Key: Value, заканчивающихся пустой строкой. Возвращаемый map m сопоставляет CanonicalMIMEHeaderKey(ключ) последовательности значений в том же порядке, в котором они встречаются во входных данных.
Например, рассмотрим такой ввод:
My-Key: Value 1
Long-Key: Even
Longer Value
My-Key: Value 2
В данном случае ReadMIMEHeader возвращает map:
map[string][]string{
"My-Key": {"Value 1", "Value 2"},
"Long-Key": {"Even Longer Value"},
}
func (*Reader) ReadResponse
func (r *Reader) ReadResponse(expectCode int) (code int, message string, err error)
ReadResponse считывает многострочный ответ в формате:
code-message line 1 code-message line 2 ... code message line n
где код представляет собой трёхзначный код состояния. Первая строка начинается с кода и дефиса. Ответ завершается строкой, начинающейся с того же кода, за которым следует пробел. Каждая строка в сообщении разделена символом новой строки (\n).
См. страницу 36 RFC 959 (https://www.ietf.org/rfc/rfc959.txt) для получения подробной информации о другом формате ответа, который принимается:
code-message line 1 message line 2 ... code message line n
Если префикс статуса не совпадает с цифрами в expectCode, ReadResponse возвращает ошибку с err, установленным в &Error{code, message}. Например, если expectCode равен 31, ошибка будет возвращена, если статус не находится в диапазоне [310,319].
expectCode <= 0 отключает проверку кода состояния.
type Writer
Writer реализует удобные методы для записи запросов или ответов в текстовое сетевое соединение протокола.
type Writer struct {
W *bufio.Writer
// contains filtered or unexported fields
}
func NewWriter
func NewWriter(w *bufio.Writer) *Writer
NewWriter возвращает новый Writer, записывающий в w.
func (*Writer) DotWriter
func (w *Writer) DotWriter() io.WriteCloser
DotWriter возвращает writer, который можно использовать для записи кодировки точек в w. Он обрабатывает вставку ведущих точек при необходимости, перевод новых строк \n в \r\n и добавление заключительной строки .\r\n при закрытии DotWriter. Вызывающий метод должен закрыть DotWriter перед следующим вызовом метода w.
См. документацию для метода Reader.DotReader для получения подробной информации о кодировке точек.
func (*Writer) PrintfLine
func (w *Writer) PrintfLine(format string, args ...any) error
PrintfLine записывает отформатированный вывод, за которым следует \r\n.
© Google, Inc.
Licensed under the Creative Commons Attribution License 3.0.
http://golang.org/pkg/net/textproto/
