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, its ADC file provides both token and quota-project metadata when present. If that optional file is absent, standard ADC discovery continues; other path or read errors are returned.

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) CloseIdleConnections()
  • 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)

NewADCHTTPClient constructs an OAuth-authenticated HTTP client. Initial requests are restricted to AuthConfig.AllowedOrigin, which defaults to DefaultV1BaseURL, and redirects must remain on that origin.

func NewAuthenticatedHTTPClient

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

NewAuthenticatedHTTPClient prefers an environment API key unless ADC is required. Initial requests are restricted to AuthConfig.AllowedOrigin, which defaults to DefaultV1BaseURL, and redirects must remain on that origin.

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. URL-like inputs must be hierarchical ASCII HTTP(S) URLs without userinfo; empty or invalid inputs return "".

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
	// AllowedOrigin is the hierarchical ASCII HTTP(S) origin accepted by
	// constructor-created clients. It defaults to DefaultV1BaseURL.
	AllowedOrigin string
	// TokenSource overrides ADC discovery. When set, CredentialsPath is ignored.
	TokenSource TokenSourceFunc
	// QuotaProjectID explicitly sets the x-goog-user-project header for ADC
	// clients. It takes precedence over GOOGLE_CLOUD_QUOTA_PROJECT and
	// credentials-file metadata.
	QuotaProjectID string
	// CredentialsPath returns an explicit ADC file path. When set, the path is
	// evaluated once and must be readable; ADC discovery does not fall back.
	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)

DoAPIRequest sends an authenticated API request. reqURL must be absolute and share an origin with BaseURL; redirects to another origin are rejected.

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) CloseIdleConnections

func (t *QuotaProjectTransport) CloseIdleConnections()

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
}