http

README

sacloud/go-http

さくらのクラウド向けHTTPクライアントライブラリ

概要

さくらのクラウドの各種API(IaaS,ObjectStorage,PHYなど)で共通利用できるHTTPクライアント機能を提供します。

関連プロジェクト

• sacloud/api-client-go: sacloudプロダクト向けHTTP/APIクライアントライブラリ sacloud/go-httpをラップし環境変数やUsacloud互換のプロファイルの処理などを提供します。

License

go-http Copyright (C) 2021-2023 The sacloud/go-http authors.

This project is published under Apache 2.0 License.

Documentation

Index

• Constants
• Variables
• type Client
  • func NewClient(token, secret string) *Client
  • func (c *Client) Do(req *http.Request) (*http.Response, error)
• type RateLimitRoundTripper
  • func (r *RateLimitRoundTripper) RoundTrip(req *http.Request) (*http.Response, error)
• type RequestCustomizer
  • func ComposeRequestCustomizer(funcs ...RequestCustomizer) RequestCustomizer
• type TracingRoundTripper
  • func (r *TracingRoundTripper) RoundTrip(req *http.Request) (*http.Response, error)

Constants

const Version = "0.1.8"

Version バージョン

Variables

var (
	// DefaultUserAgent デフォルトのユーザーエージェント
	DefaultUserAgent = fmt.Sprintf(
		"go-http/v%s (%s/%s; +https://github.com/sacloud/go-http)",
		Version,
		runtime.GOOS,
		runtime.GOARCH,
	)

	// DefaultAcceptLanguage デフォルトのAcceptLanguage
	DefaultAcceptLanguage = ""

	// DefaultRetryMax デフォルトのリトライ回数
	DefaultRetryMax = 10

	// DefaultRetryWaitMin デフォルトのリトライ間隔(最小)
	DefaultRetryWaitMin = 1 * time.Second

	// DefaultRetryWaitMax デフォルトのリトライ間隔(最大)
	DefaultRetryWaitMax = 64 * time.Second
)

Types

type Client

type Client struct {
	// AccessToken アクセストークン
	AccessToken string `validate:"required"`
	// AccessTokenSecret アクセストークンシークレット
	AccessTokenSecret string `validate:"required"`
	// ユーザーエージェント
	UserAgent string
	// Accept-Language
	AcceptLanguage string
	// Gzipを有効にするか
	Gzip bool
	// CheckRetryFunc リトライすべきか判定するためのfunc
	CheckRetryFunc func(ctx context.Context, resp *http.Response, err error) (bool, error)
	// リトライ回数
	RetryMax int
	// リトライ待ち時間(最小)
	RetryWaitMin time.Duration
	// リトライ待ち時間(最大)
	RetryWaitMax time.Duration
	// APIコール時に利用される*http.Client 未指定の場合http.DefaultClientが利用される
	HTTPClient *http.Client
	// RequestCustomizer リクエスト前に*http.Requestのカスタマイズを行うためのfunc
	RequestCustomizer RequestCustomizer
}

Client さくらのクラウドAPI(secure.sakura.ad.jp)向けのHTTPクライアント

レスポンスの状態に応じてリトライする仕組みを持つ デフォルトだとレスポンスステータスコード423、または503を受け取った場合にRetryMax回リトライする

リトライ間隔はRetryMinからRetryMaxまで指数的に増加する(Exponential Backoff)

リトライ時にcontext.Canceled、またはcontext.DeadlineExceededの場合はリトライしない

func NewClient

func NewClient(token, secret string) *Client

NewClient APIクライアント作成

func (*Client) Do

func (c *Client) Do(req *http.Request) (*http.Response, error)

Do APIコール実施

type RateLimitRoundTripper

type RateLimitRoundTripper struct {
	// Transport 親となるhttp.RoundTripper、nilの場合http.DefaultTransportが利用される
	Transport http.RoundTripper
	// RateLimitPerSec 秒あたりのリクエスト数
	RateLimitPerSec int
	// contains filtered or unexported fields
}

RateLimitRoundTripper 秒間アクセス数を制限するためのhttp.RoundTripper実装

func (*RateLimitRoundTripper) RoundTrip

func (r *RateLimitRoundTripper) RoundTrip(req *http.Request) (*http.Response, error)

RoundTrip http.RoundTripperの実装

type RequestCustomizer

type RequestCustomizer func(r *http.Request) error

RequestCustomizer リクエスト前に*http.Requestのカスタマイズを行うためのfunc

func ComposeRequestCustomizer

func ComposeRequestCustomizer(funcs ...RequestCustomizer) RequestCustomizer

ComposeRequestCustomizer 任意の個数のRequestCustomizerを合成してRequestCustomizerを返す

複数のRequestCustomizerを指定した場合は先頭から呼びだされ、エラーを返したら即時returnする

type TracingRoundTripper

type TracingRoundTripper struct {
	// Transport 親となるhttp.RoundTripper、nilの場合http.DefaultTransportが利用される
	Transport http.RoundTripper
	// OutputOnlyError trueの場合レスポンスのステータスコードが200番台の時はリクエスト/レスポンスのトレースを出力しない
	OutputOnlyError bool
}

TracingRoundTripper リクエスト/レスポンスのトレースログを出力するためのhttp.RoundTripper実装

Client.Gzipがtrueの場合でも関知しないため利用者側で制御する必要がある

func (*TracingRoundTripper) RoundTrip

func (r *TracingRoundTripper) RoundTrip(req *http.Request) (*http.Response, error)

RoundTrip http.RoundTripperの実装