dkapi

README

developerknowledge-go

Go helpers for the Google Developer Knowledge API.

This module provides shared primitives used by Developer Knowledge API clients:

• API key and ADC authentication helpers
• quota project handling for local ADC (including CLOUDSDK_CONFIG)
• Google API error parsing with bounded error-body reads
• rate limit error handling and Retry-After parsing
• context-aware HTTP request helpers
• documents:batchGet support with chunking via BatchGetDocumentsAll
• shared Document and DocumentChunk response types
• conservative batch bisection error classification

See pkg.go.dev for API documentation. This module complements the official generated client at google.golang.org/api/developerknowledge/v1; see repository issues for the long-term direction.

Install

go get github.com/apstndb/developerknowledge-go

Example

import (
    "context"

    dkapi "github.com/apstndb/developerknowledge-go"
)

ctx := context.Background()
client, apiKey, err := dkapi.NewAuthenticatedHTTPClient(ctx, dkapi.AuthConfig{
    Mode:    dkapi.AuthPreferAPIKey,
    Timeout: dkapi.DefaultHTTPTimeout,
})
if err != nil {
    return err
}

dkClient := &dkapi.Client{
    BaseURL:    dkapi.DefaultV1BaseURL,
    APIKey:     apiKey,
    HTTPClient: client,
}

docs, err := dkClient.BatchGetDocuments(ctx, []string{
    "documents/developers.google.com/knowledge/api",
})

Documentation

Overview

Package dkapi provides shared primitives for Google Developer Knowledge API clients.

This module complements (rather than replaces) the official generated client at google.golang.org/api/developerknowledge/v1. It focuses on auth-mode selection, quota-project handling for local ADC, rate-limit retry, batch bisection helpers, and document-name normalization used by dkcli, gcp-docs-mirror-tools, and spanner-mycli.

Authentication supports API keys (DEVELOPERKNOWLEDGE_API_KEY or GOOGLE_API_KEY) and Application Default Credentials. When CLOUDSDK_CONFIG is set, both token and quota-project metadata are read from that directory's ADC file.

Index

• Constants
• func APIKeyFromEnv() string
• func CheckResponse(resp *http.Response) ([]byte, error)
• func DefaultADCCredentialsPath(goos, homeDir, appData string) string
• func DefaultCredentialsPath() string
• func IsBisectableDocumentError(err error) bool
• func NewADCHTTPClient(ctx context.Context, cfg AuthConfig) (*http.Client, error)
• func NewAuthenticatedHTTPClient(ctx context.Context, cfg AuthConfig) (*http.Client, string, error)
• func NormalizeDocName(name string) string
• func ParseRetryAfter(resp *http.Response) time.Duration
• func SleepContext(ctx context.Context, wait time.Duration) error
• type ADCCredentialsMetadata
  • func LoadADCCredentialsMetadata(credentialsPath func() string) ADCCredentialsMetadata
  • func ResolveQuotaProjectID(credentialsPath func() string) (string, ADCCredentialsMetadata)
• type APIError
  • func (e *APIError) Error() string
• type AuthConfig
• type AuthMode
• type BatchGetResponse
• type Client
  • func (c *Client) BatchGetDocuments(ctx context.Context, names []string) ([]Document, error)
  • func (c *Client) BatchGetDocumentsAll(ctx context.Context, names []string) ([]Document, error)
  • func (c *Client) DoAPIRequest(ctx context.Context, method, reqURL string, body []byte, contentType string) ([]byte, error)
  • func (c *Client) DoGet(ctx context.Context, reqURL string) ([]byte, error)
  • func (c *Client) DoJSONPost(ctx context.Context, reqURL string, body []byte) ([]byte, error)
• type Document
• type DocumentChunk
• type QuotaProjectTransport
  • func (t *QuotaProjectTransport) RoundTrip(req *http.Request) (*http.Response, error)
• type RateLimitError
  • func (e *RateLimitError) Error() string
• type TokenSourceFunc
• type Waiter

Constants

const (
	CloudPlatformScope = "https://www.googleapis.com/auth/cloud-platform"
	DefaultV1BaseURL   = "https://developerknowledge.googleapis.com/v1"
	DefaultHTTPTimeout = time.Minute
	// MaxBatchGetDocuments is the maximum number of document names accepted by
	// documents:batchGet. Documents are returned in the same order as names.
	MaxBatchGetDocuments = 20
)

Functions

func APIKeyFromEnv

func APIKeyFromEnv() string

func CheckResponse

func CheckResponse(resp *http.Response) ([]byte, error)

func DefaultADCCredentialsPath

func DefaultADCCredentialsPath(goos, homeDir, appData string) string

func DefaultCredentialsPath

func DefaultCredentialsPath() string

func IsBisectableDocumentError

func IsBisectableDocumentError(err error) bool

func NewADCHTTPClient

func NewADCHTTPClient(ctx context.Context, cfg AuthConfig) (*http.Client, error)

func NewAuthenticatedHTTPClient

func NewAuthenticatedHTTPClient(ctx context.Context, cfg AuthConfig) (*http.Client, string, error)

func NormalizeDocName

func NormalizeDocName(name string) string

NormalizeDocName converts a pasted URL or short document path into a Developer Knowledge API resource name (documents/...). Query strings, fragments, and trailing slashes are stripped.

func ParseRetryAfter

func ParseRetryAfter(resp *http.Response) time.Duration

func SleepContext

func SleepContext(ctx context.Context, wait time.Duration) error

Types

type ADCCredentialsMetadata

type ADCCredentialsMetadata struct {
	Type           string `json:"type"`
	QuotaProjectID string `json:"quota_project_id"`
}

func LoadADCCredentialsMetadata

func LoadADCCredentialsMetadata(credentialsPath func() string) ADCCredentialsMetadata

func ResolveQuotaProjectID

func ResolveQuotaProjectID(credentialsPath func() string) (string, ADCCredentialsMetadata)

type APIError

type APIError struct {
	Code    int
	Status  string
	Message string
}

func (*APIError) Error

func (e *APIError) Error() string

type AuthConfig

type AuthConfig struct {
	Mode            AuthMode
	Timeout         time.Duration
	TokenSource     TokenSourceFunc
	CredentialsPath func() string
}

type AuthMode

type AuthMode int

const (
	AuthPreferAPIKey AuthMode = iota
	AuthRequireADC
)

type BatchGetResponse

type BatchGetResponse struct {
	Documents []Document `json:"documents" yaml:"documents"`
}

type Client

type Client struct {
	BaseURL       string
	APIKey        string
	HTTPClient    *http.Client
	Limiter       Waiter
	Verbose       bool
	VerboseWriter io.Writer
	// MaxRetries is the number of additional attempts after the first request.
	MaxRetries int
}

func (*Client) BatchGetDocuments

func (c *Client) BatchGetDocuments(ctx context.Context, names []string) ([]Document, error)

func (*Client) BatchGetDocumentsAll

func (c *Client) BatchGetDocumentsAll(ctx context.Context, names []string) ([]Document, error)

BatchGetDocumentsAll fetches documents in chunks of MaxBatchGetDocuments while preserving the order of names. Invalid names fail the whole batch for that chunk.

func (*Client) DoAPIRequest

func (c *Client) DoAPIRequest(ctx context.Context, method, reqURL string, body []byte, contentType string) ([]byte, error)

func (*Client) DoGet

func (c *Client) DoGet(ctx context.Context, reqURL string) ([]byte, error)

func (*Client) DoJSONPost

func (c *Client) DoJSONPost(ctx context.Context, reqURL string, body []byte) ([]byte, error)

type Document

type Document struct {
	Name               string `json:"name" yaml:"name"`
	URI                string `json:"uri" yaml:"uri"`
	Content            string `json:"content,omitempty" yaml:"content,omitempty"`
	Description        string `json:"description,omitempty" yaml:"description,omitempty"`
	DataSource         string `json:"dataSource,omitempty" yaml:"data_source,omitempty"`
	Title              string `json:"title,omitempty" yaml:"title,omitempty"`
	UpdateTime         string `json:"updateTime,omitempty" yaml:"update_time,omitempty"`
	View               string `json:"view,omitempty" yaml:"view,omitempty"`
	ContentLengthBytes int64  `json:"contentLengthBytes,omitempty" yaml:"content_length_bytes,omitempty"`
}

type DocumentChunk

type DocumentChunk struct {
	Parent   string    `json:"parent" yaml:"parent"`
	ID       string    `json:"id" yaml:"id"`
	Content  string    `json:"content" yaml:"content"`
	Document *Document `json:"document,omitempty" yaml:"document,omitempty"`
}

type QuotaProjectTransport

type QuotaProjectTransport struct {
	Base    http.RoundTripper
	Project string
}

func (*QuotaProjectTransport) RoundTrip

func (t *QuotaProjectTransport) RoundTrip(req *http.Request) (*http.Response, error)

type RateLimitError

type RateLimitError struct {
	RetryAfter time.Duration
}

func (*RateLimitError) Error

func (e *RateLimitError) Error() string

type TokenSourceFunc

type TokenSourceFunc func(context.Context, ...string) (oauth2.TokenSource, error)

var DefaultTokenSource TokenSourceFunc = func(ctx context.Context, scopes ...string) (oauth2.TokenSource, error) {
	return google.DefaultTokenSource(ctx, scopes...)
}

type Waiter

type Waiter interface {
	Wait(context.Context) error
}