web

Documentation

Overview

Package web is a Go client for Geni.com's internal AJAX endpoints — the same calls the geni.com website makes from a logged-in browser.

These endpoints are undocumented, unsupported by Geni.com, and may change or break without notice. Using this package may violate geni.com's Terms of Service — review them before use. The package is intended for personal interop with your own genealogy data (e.g. migration tooling) and does not bypass authentication: it requires cookies from a logged-in browser session you established yourself.

The package is structurally independent of the OAuth client in the repository's root and resource sub-packages. It uses cookie auth and per-form CSRF tokens, returns parsed Go values (never HTML), and ships with a conservative 1 req/sec default rate limit.

Index

• Variables
• func CookiesFromHeader(header string) []*http.Cookie
• type Client
  • func NewClient(opts Options) (*Client, error)
  • func (c *Client) BaseURL() string
  • func (c *Client) CSRFToken(ctx context.Context) (string, error)
  • func (c *Client) Do(req *http.Request) (*http.Response, error)
  • func (c *Client) InvalidateCSRF()
• type Options

Variables

var (
	// ErrNoCookies is returned by NewClient when Options.Cookies is nil.
	// The Web client never logs in itself; the caller must supply a
	// cookie jar obtained from a logged-in browser.
	ErrNoCookies = errors.New("web: no cookies supplied (use CookiesFromHeader or CookiesFromJar)")

	// ErrNotLoggedIn is returned when the response indicates the session
	// is missing or expired (typically a 302 redirect to /login).
	ErrNotLoggedIn = errors.New("web: not logged in (session cookie missing or expired)")

	// ErrBlocked is returned when geni.com's edge serves an Incapsula /
	// bot-challenge page instead of the requested content.
	ErrBlocked = errors.New("web: request blocked by upstream bot protection")

	// ErrCSRFExpired is returned when geni.com rejects a request with an
	// expired authenticity_token. Callers normally do not see this — the
	// client refreshes and retries internally.
	ErrCSRFExpired = errors.New("web: CSRF authenticity_token rejected")
)

Functions

func CookiesFromHeader

func CookiesFromHeader(header string) []*http.Cookie

CookiesFromHeader parses a "name=value; name=value" cookie header (the form copied out of a browser's DevTools Network panel) into a slice of *http.Cookie suitable for Options.Cookies.

Types

type Client

type Client struct {
	// contains filtered or unexported fields
}

Client is the AJAX Web client. Construct it once per session; resource sub-packages (web/revision, web/document) wrap *Client.

func NewClient

func NewClient(opts Options) (*Client, error)

NewClient returns a Client configured from opts.

func (*Client) BaseURL

func (c *Client) BaseURL() string

BaseURL returns the configured base URL (no trailing slash).

func (*Client) CSRFToken

func (c *Client) CSRFToken(ctx context.Context) (string, error)

CSRFToken returns the current authenticity_token, fetching and caching it on first use. Safe for concurrent use.

func (*Client) Do

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

Do sends req. It enforces the rate limit, attaches the User-Agent, follows redirects only inside geni.com (a redirect to /login becomes ErrNotLoggedIn), and detects Incapsula block pages.

func (*Client) InvalidateCSRF

func (c *Client) InvalidateCSRF()

InvalidateCSRF clears the cached authenticity_token so the next CSRFToken call refetches it.

type Options

type Options struct {
	// Cookies carries the geni.com session. NewClient installs them on
	// a cookie jar scoped to BaseURL. Build with CookiesFromHeader for
	// the common case (paste from DevTools).
	Cookies []*http.Cookie

	// UserAgent is sent on every request. Defaults to "go-geni-web/1
	// (+https://github.com/dmalch/go-geni)".
	UserAgent string

	// BaseURL overrides the default https://www.geni.com host. Useful
	// for tests; production callers should leave it empty.
	BaseURL string

	// HTTPClient overrides the default *http.Client. The package
	// always sets the client's Jar to Cookies, so the override does
	// not need to.
	HTTPClient *http.Client

	// RateLimit caps outgoing requests in requests-per-second.
	// Defaults to 1 rps if unset or non-positive. Increase only when
	// you knowingly accept the additional load on your own account.
	RateLimit float64

	// CSRFSourcePath overrides the path the Client fetches to scrape
	// the authenticity_token. Defaults to
	// "/documents/save_document_content" — any page that renders a
	// Geni form with a CSRF input works.
	CSRFSourcePath string
}

Options configures a Web Client. Cookies is the only required field.