Documentation
¶
Overview ¶
パッケージtextprotoは、HTTP、NNTP、およびSMTPのスタイルでテキストベースのリクエスト/レスポンスプロトコルの汎用サポートを実装します。
このパッケージでは以下を提供します:
Errorは、サーバーからの数値エラーレスポンスを表します。
Pipelineは、クライアントでパイプライン化されたリクエストとレスポンスを管理するためのものです。
Readerは、数値応答コードライン、キー: 値のヘッダ、先行スペースで折り返された行、独自の行にドットで終わる全文テキストブロックを読み取るためのものです。
Writerは、ドットエンコードされたテキストブロックを書き込むためのものです。
Connは、単一のネットワーク接続で使用するための、Reader、Writer、およびPipelineの便利なパッケージングです。
Index ¶
- func CanonicalMIMEHeaderKey(s string) string
- func TrimBytes(b []byte) []byte
- func TrimString(s string) string
- type Conn
- type Error
- type MIMEHeader
- type Pipeline
- type ProtocolError
- type Reader
- func (r *Reader) DotReader() io.Reader
- func (r *Reader) ReadCodeLine(expectCode int) (code int, message string, err error)
- func (r *Reader) ReadContinuedLine() (string, error)
- func (r *Reader) ReadContinuedLineBytes() ([]byte, error)
- func (r *Reader) ReadDotBytes() ([]byte, error)
- func (r *Reader) ReadDotLines() ([]string, error)
- func (r *Reader) ReadLine() (string, error)
- func (r *Reader) ReadLineBytes() ([]byte, error)
- func (r *Reader) ReadMIMEHeader() (MIMEHeader, error)
- func (r *Reader) ReadResponse(expectCode int) (code int, message string, err error)
- type Writer
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func CanonicalMIMEHeaderKey ¶
CanonicalMIMEHeaderKeyは、MIMEヘッダーキーsの正準形を返します。正準化は、 最初の文字とハイフンの後に続くすべての文字を大文字に変換し、 残りの文字は小文字に変換します。たとえば、 "accept-encoding"の正規キーは"Accept-Encoding"です。 MIMEヘッダーキーはASCIIのみとします。 sにスペースや無効なヘッダーフィールドバイトが含まれている場合、 変更せずに返されます。
func TrimString ¶ added in v1.1.0
TrimStringは、先頭と末尾のASCIIスペースを除いたsを返します。
Types ¶
type Conn ¶
Connはテキストネットワークプロトコルの接続を表します。 それは、I/Oを管理するためのReaderとWriter、および接続上で並行リクエストをシーケンスするためのパイプラインで構成されています。 これらの埋め込まれた型は、それらの型のドキュメントで詳細なメソッドを持っています。
func (*Conn) Cmd ¶
Cmdはパイプラインの順番を待ってからコマンドを送る便利なメソッドです。コマンドのテキストは、formatとargsを使用してフォーマットし、\r\nを追加した結果です。CmdはコマンドのIDを返し、StartResponseとEndResponseで使用します。 例えば、クライアントはHELPコマンドを実行し、ドットボディを返すかもしれません: 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)
type MIMEHeader ¶
MIMEHeaderは、キーと値のセットへのマッピングを表すMIMEスタイルのヘッダーです。
func (MIMEHeader) Add ¶
func (h MIMEHeader) Add(key, value string)
Addは、キーと値のペアをヘッダーに追加します。 キーに関連付けられている既存の値に追記されます。
func (MIMEHeader) Get ¶
func (h MIMEHeader) Get(key string) string
Getは与えられたキーに関連付けられた最初の値を取得します。 大文字と小文字を区別しないです。CanonicalMIMEHeaderKeyが提供されたキーを正規化するために使用されます。 キーに関連付けられた値がない場合、Getは "" を返します。 正規化されていないキーを使用する場合は、直接マップにアクセスしてください。
func (MIMEHeader) Set ¶
func (h MIMEHeader) Set(key, value string)
Setは、キーに関連付けられたヘッダーエントリを単一の要素"value"に設定します。既存の値は置き換えられます。
func (MIMEHeader) Values ¶ added in v1.14.0
func (h MIMEHeader) Values(key string) []string
Valuesは与えられたキーに関連付けられたすべての値を返します。 大文字小文字を区別しません。CanonicalMIMEHeaderKeyを使って提供されたキーを正規化します。 正規化されていないキーを使用する場合は、マップに直接アクセスしてください。 返されるスライスはコピーされません。
type Pipeline ¶
type Pipeline struct {
// contains filtered or unexported fields
}
パイプラインは、順番にリクエストとレスポンスを管理するためのものです。
接続上の複数のクライアントを管理するために、Pipeline p を使用する場合、 それぞれのクライアントは次のように実行する必要があります:
id := p.Next() // 番号を取得する p.StartRequest(id) // リクエストを送信する順番を待つ «リクエストを送信する» p.EndRequest(id) // リクエストの送信が完了したことをPipelineに通知する p.StartResponse(id) // レスポンスを読み取る順番を待つ «レスポンスを読み取る» p.EndResponse(id) // レスポンスの読み取りが完了したことをPipelineに通知する
パイプラインサーバーでも、同じ呼び出しを使用して、並列で計算されたレスポンスを正しい順序で書き込むことができます。
func (*Pipeline) EndRequest ¶
EndRequestは、与えられたIDを持つリクエストが送信されたことをpに通知します (または、これがサーバーの場合は受信されました)。
func (*Pipeline) EndResponse ¶
EndResponseは、指定されたIDのレスポンスが受信されたことをpに通知します (または、サーバーの場合は送信されます)。
func (*Pipeline) StartRequest ¶
StartRequestは、指定したIDでリクエストを送信(または、サーバーの場合は受信)する時間になるまでブロックします。
func (*Pipeline) StartResponse ¶
StartResponseは、指定したidのリクエストを受信する(または、サーバーの場合は送信する)時までブロックします。
type ProtocolError ¶
type ProtocolError string
ProtocolErrorは、無効なレスポンスや切断された接続など、プロトコル違反を示すものです。
func (ProtocolError) Error ¶
func (p ProtocolError) Error() string
type Reader ¶
Readerは、テキストプロトコルネットワーク接続からリクエストまたはレスポンスを読み取るための便利なメソッドを実装します。
func NewReader ¶
NewReaderはrから読み取りを行う新しいReaderを返します。
サービス拒否攻撃を避けるために、提供されたbufio.Readerは io.LimitReaderまたは同様のReaderから読み取るようになっている必要があります。
func (*Reader) DotReader ¶
DotReaderは、rから読み込まれたドットエンコードされたブロックのデコードされたテキストを使用して、 Readsを満たす新しいReaderを返します。 返されたReaderは、次にrのメソッドが呼び出されるまでの間のみ有効です。
ドットエンコーディングは、SMTPなどのテキストプロトコルで使用される一般的なフレーミングです。 データは、各行が"\r\n"で終わるシーケンスです。シーケンス自体は、単独のドット「.」の行で終了します:".\r\n"。 ドットで始まる行は、シーケンスの終わりのように見えないように追加のドットでエスケープされます。
ReaderのReadメソッドによって返されるデコードされた形式は、"\r\n"の行末をよりシンプルな"\n"に書き換え、 先頭のドットエスケープを削除し、シーケンスの終了行を消費(および破棄)した後にエラーio.EOFで停止します。
func (*Reader) ReadCodeLine ¶
ReadCodeLineは、下記の形式の応答コード行を読み取ります:
code message
ここで、codeは3桁のステータスコードであり、messageは行の残りの部分に拡張されます。 このような行の例は次の通りです:
220 plan9.bell-labs.com ESMTP
もしステータスのプレフィックスがexpectCodeの数字と一致しない場合、ReadCodeLineはerrを&Error{code, message}に設定して返します。 例えば、expectCodeが31である場合、ステータスが[310,319]の範囲にない場合はエラーが返されます。
もし応答が複数行の場合、ReadCodeLineはエラーを返します。
expectCodeが0以下の場合、ステータスコードのチェックは無効になります。
func (*Reader) ReadContinuedLine ¶
ReadContinuedLineは、rから可能性がある継続行を読み取ります。 最後の余分なASCII空白は省略されます。 最初の行以降の行は、スペースまたはタブ文字で始まる場合には、 継続行と見なされます。返されるデータでは、 継続行は前の行とスペース1つのみで区切られます: 改行と先頭の空白は削除されます。
例えば、次の入力を考えてみてください:
Line 1 continued... Line 2
ReadContinuedLineの最初の呼び出しは「Line 1 continued...」を返し、 2番目の呼び出しは「Line 2」を返します。
空行は継続されません。
func (*Reader) ReadContinuedLineBytes ¶
ReadContinuedLineBytesは、ReadContinuedLineと同様ですが、 文字列ではなく[]byteを返します。
func (*Reader) ReadDotBytes ¶
ReadDotBytesはドットエンコーディングを読み込み、デコードされたデータを返します。
ドットエンコーディングの詳細については、DotReaderメソッドのドキュメントを参照してください。
func (*Reader) ReadDotLines ¶
ReadDotLines関数はドットエンコーディングを読み取り、各行から最後の\r\nまたは\nを省いたデコードされたスライスを返します。
dot-encodingの詳細についてはDotReaderメソッドのドキュメントを参照してください。
func (*Reader) ReadLineBytes ¶
ReadLineBytesは、文字列の代わりに[]byteを返すReadLineと同様の機能です。
func (*Reader) ReadMIMEHeader ¶
func (r *Reader) ReadMIMEHeader() (MIMEHeader, error)
ReadMIMEHeaderはrからMIME形式のヘッダーを読み取ります。 ヘッダーは、連続したキー:値行のシーケンスで、 空行で終わる可能性があります。 返されるマップmは、CanonicalMIMEHeaderKey(key)をキーとし、 入力で遭遇した順に値のシーケンスをマッピングします。
例えば、以下のような入力を考えてください:
My-Key: Value 1 Long-Key: Even Longer Value My-Key: Value 2
この入力が与えられた場合、ReadMIMEHeaderは以下のマップを返します:
map[string][]string{ "My-Key": {"Value 1", "Value 2"}, "Long-Key": {"Even Longer Value"}, }
func (*Reader) ReadResponse ¶
ReadResponseは以下の形式の複数行のレスポンスを読み込みます:
code-message 行1 code-message 行2 ... code message 行n
ここで、codeは3桁のステータスコードです。最初の行はcodeとハイフンで始まります。 レスポンスは、同じcodeの後にスペースが続く行で終了します。 メッセージ中の各行は改行(\n)で区切られます。
別の形式のレスポンスの詳細については、RFC 959(https://www.ietf.org/rfc/rfc959.txt)の 36ページを参照してください:
code-message 行1 message 行2 ... code message 行n
ステータスのプレフィックスがexpectCodeの数字と一致しない場合、 ReadResponseはerrを設定した&Error{code, message}として返されます。 たとえば、expectCodeが31の場合、ステータスが[310、319]の範囲内でない場合、エラーが返されます。
expectCode <= 0の場合、ステータスコードのチェックは無効になります。
type Writer ¶
Writerは、テキストプロトコルネットワーク接続にリクエストまたはレスポンスを書き込むための便利なメソッドを実装します。
func (*Writer) DotWriter ¶
func (w *Writer) DotWriter() io.WriteCloser
DotWriterは、wにドットエンコードを書き込むために使用できるライターを返します。 必要な場合に先行するドットを挿入し、改行文字 \n を \r\n に変換し、 DotWriterが閉じられるときに最後の .\r\n 行を追加します。 次にwのメソッドを呼び出す前に、呼び出し元はDotWriterを閉じる必要があります。
dot-encodingの詳細については、ReaderのDotReaderメソッドのドキュメントを参照してください。