textproto

package
v1.21.10 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Feb 7, 2024 License: MIT Imports: 3 Imported by: 0

Documentation

Overview

パッケージtextprotoは、HTTP、NNTP、およびSMTPのスタイルでテキストベースのリクエスト/レスポンスプロトコルの汎用サポートを実装します。

このパッケージでは以下を提供します:

Errorは、サーバーからの数値エラーレスポンスを表します。

Pipelineは、クライアントでパイプライン化されたリクエストとレスポンスを管理するためのものです。

Readerは、数値応答コードライン、キー: 値のヘッダ、先行スペースで折り返された行、独自の行にドットで終わる全文テキストブロックを読み取るためのものです。

Writerは、ドットエンコードされたテキストブロックを書き込むためのものです。

Connは、単一のネットワーク接続で使用するための、Reader、Writer、およびPipelineの便利なパッケージングです。

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func CanonicalMIMEHeaderKey

func CanonicalMIMEHeaderKey(s string) string

CanonicalMIMEHeaderKeyは、MIMEヘッダーキーsの正準形を返します。正準化は、 最初の文字とハイフンの後に続くすべての文字を大文字に変換し、 残りの文字は小文字に変換します。たとえば、 "accept-encoding"の正規キーは"Accept-Encoding"です。 MIMEヘッダーキーはASCIIのみとします。 sにスペースや無効なヘッダーフィールドバイトが含まれている場合、 変更せずに返されます。

func TrimBytes added in v1.1.0

func TrimBytes(b []byte) []byte

TrimBytesは、先頭と末尾のASCIIスペースを除いたbを返します。

func TrimString added in v1.1.0

func TrimString(s string) string

TrimStringは、先頭と末尾のASCIIスペースを除いたsを返します。

Types

type Conn

type Conn struct {
	Reader
	Writer
	Pipeline
	// contains filtered or unexported fields
}

Connはテキストネットワークプロトコルの接続を表します。 それは、I/Oを管理するためのReaderとWriter、および接続上で並行リクエストをシーケンスするためのパイプラインで構成されています。 これらの埋め込まれた型は、それらの型のドキュメントで詳細なメソッドを持っています。

func Dial

func Dial(network, addr string) (*Conn, error)

Dialは、net.Dialを使って指定されたネットワークの指定されたアドレスに接続し、接続のための新しいConnを返します。

func NewConn

func NewConn(conn io.ReadWriteCloser) *Conn

NewConnはI/Oに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コマンドを実行し、ドットボディを返すかもしれません: 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 Error

type Error struct {
	Code int
	Msg  string
}

Errorは、サーバーからの数値エラーレスポンスを表します。

func (*Error) Error

func (e *Error) Error() string

type MIMEHeader

type MIMEHeader map[string][]string

MIMEHeaderは、キーと値のセットへのマッピングを表すMIMEスタイルのヘッダーです。

func (MIMEHeader) Add

func (h MIMEHeader) Add(key, value string)

Addは、キーと値のペアをヘッダーに追加します。 キーに関連付けられている既存の値に追記されます。

func (MIMEHeader) Del

func (h MIMEHeader) Del(key string)

Delはkeyに関連付けられた値を削除します。

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

func (p *Pipeline) EndRequest(id uint)

EndRequestは、与えられたIDを持つリクエストが送信されたことをpに通知します (または、これがサーバーの場合は受信されました)。

func (*Pipeline) EndResponse

func (p *Pipeline) EndResponse(id uint)

EndResponseは、指定されたIDのレスポンスが受信されたことをpに通知します (または、サーバーの場合は送信されます)。

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のリクエストを受信する(または、サーバーの場合は送信する)時までブロックします。

type ProtocolError

type ProtocolError string

ProtocolErrorは、無効なレスポンスや切断された接続など、プロトコル違反を示すものです。

func (ProtocolError) Error

func (p ProtocolError) Error() string

type Reader

type Reader struct {
	R *bufio.Reader
	// contains filtered or unexported fields
}

Readerは、テキストプロトコルネットワーク接続からリクエストまたはレスポンスを読み取るための便利なメソッドを実装します。

func NewReader

func NewReader(r *bufio.Reader) *Reader

NewReaderはrから読み取りを行う新しいReaderを返します。

サービス拒否攻撃を避けるために、提供されたbufio.Readerは io.LimitReaderまたは同様のReaderから読み取るようになっている必要があります。

func (*Reader) DotReader

func (r *Reader) DotReader() io.Reader

DotReaderは、rから読み込まれたドットエンコードされたブロックのデコードされたテキストを使用して、 Readsを満たす新しいReaderを返します。 返されたReaderは、次にrのメソッドが呼び出されるまでの間のみ有効です。

ドットエンコーディングは、SMTPなどのテキストプロトコルで使用される一般的なフレーミングです。 データは、各行が"\r\n"で終わるシーケンスです。シーケンス自体は、単独のドット「.」の行で終了します:".\r\n"。 ドットで始まる行は、シーケンスの終わりのように見えないように追加のドットでエスケープされます。

ReaderのReadメソッドによって返されるデコードされた形式は、"\r\n"の行末をよりシンプルな"\n"に書き換え、 先頭のドットエスケープを削除し、シーケンスの終了行を消費(および破棄)した後にエラーio.EOFで停止します。

func (*Reader) ReadCodeLine

func (r *Reader) ReadCodeLine(expectCode int) (code int, message string, err error)

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

func (r *Reader) ReadContinuedLine() (string, error)

ReadContinuedLineは、rから可能性がある継続行を読み取ります。 最後の余分なASCII空白は省略されます。 最初の行以降の行は、スペースまたはタブ文字で始まる場合には、 継続行と見なされます。返されるデータでは、 継続行は前の行とスペース1つのみで区切られます: 改行と先頭の空白は削除されます。

例えば、次の入力を考えてみてください:

Line 1
  continued...
Line 2

ReadContinuedLineの最初の呼び出しは「Line 1 continued...」を返し、 2番目の呼び出しは「Line 2」を返します。

空行は継続されません。

func (*Reader) ReadContinuedLineBytes

func (r *Reader) ReadContinuedLineBytes() ([]byte, error)

ReadContinuedLineBytesは、ReadContinuedLineと同様ですが、 文字列ではなく[]byteを返します。

func (*Reader) ReadDotBytes

func (r *Reader) ReadDotBytes() ([]byte, error)

ReadDotBytesはドットエンコーディングを読み込み、デコードされたデータを返します。

ドットエンコーディングの詳細については、DotReaderメソッドのドキュメントを参照してください。

func (*Reader) ReadDotLines

func (r *Reader) ReadDotLines() ([]string, error)

ReadDotLines関数はドットエンコーディングを読み取り、各行から最後の\r\nまたは\nを省いたデコードされたスライスを返します。

dot-encodingの詳細についてはDotReaderメソッドのドキュメントを参照してください。

func (*Reader) ReadLine

func (r *Reader) ReadLine() (string, error)

ReadLineはrから1行だけ読み取り、返された文字列から最後の\nまたは\r\nを省略します。

func (*Reader) ReadLineBytes

func (r *Reader) ReadLineBytes() ([]byte, error)

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

func (r *Reader) ReadResponse(expectCode int) (code int, message string, err error)

ReadResponseは以下の形式の複数行のレスポンスを読み込みます:

code-message 行1
code-message 行2
...
code message 行n

ここで、codeは3桁のステータスコードです。最初の行はcodeとハイフンで始まります。 レスポンスは、同じcodeの後にスペースが続く行で終了します。 メッセージ中の各行は改行(\n)で区切られます。

別の形式のレスポンスの詳細については、RFC 959https://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

type Writer struct {
	W *bufio.Writer
	// contains filtered or unexported fields
}

Writerは、テキストプロトコルネットワーク接続にリクエストまたはレスポンスを書き込むための便利なメソッドを実装します。

func NewWriter

func NewWriter(w *bufio.Writer) *Writer

NewWriterはwに書き込む新しいWriterを返します。

func (*Writer) DotWriter

func (w *Writer) DotWriter() io.WriteCloser

DotWriterは、wにドットエンコードを書き込むために使用できるライターを返します。 必要な場合に先行するドットを挿入し、改行文字 \n を \r\n に変換し、 DotWriterが閉じられるときに最後の .\r\n 行を追加します。 次にwのメソッドを呼び出す前に、呼び出し元はDotWriterを閉じる必要があります。

dot-encodingの詳細については、ReaderのDotReaderメソッドのドキュメントを参照してください。

func (*Writer) PrintfLine

func (w *Writer) PrintfLine(format string, args ...any) error

PrintfLineはフォーマットされた出力を\r\nに続けて書き込みます。

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL