client

Documentation

Overview

Package client is what a UI behind the portal needs of it: who is logged in, which servers they reach, and an HTTP client per server that carries the portal's static header and, when the portal says a server's token is missing or expiring, refreshes -- once, one refresh at a time -- and sends the request again.

The go-fileshare console calls the admin API with it (Connect); the explorer, WebDAV. Neither sees a token: the portal holds them.

Index

• Constants
• Variables
• type Doer
  • func (d *Doer) Do(req *http.Request) (*http.Response, error)
• type Portal
  • func New(base string, hc *http.Client, serialize func(func() error) error) *Portal
  • func (p *Portal) Base() string
  • func (p *Portal) Doer(server string, maxBody int64) *Doer
  • func (p *Portal) EnsureToken(ctx context.Context, server string) error
  • func (p *Portal) LoginURL(returnTo string) string
  • func (p *Portal) Logout(ctx context.Context) (string, error)
  • func (p *Portal) Session(ctx context.Context) (*Session, error)
• type RefreshError
  • func (e *RefreshError) Error() string
• type Server
  • func (s Server) Name() string
• type Session
  • func (s *Session) Who() string

Constants

const MaxInUse = 5

MaxInUse is how many servers' tokens one refresh asks for: the ones most recently used. The portal keeps its session in cookies a load balancer bounds (8 KiB of header at nginx's default); five tokens of about 1 KB fit.

const RefreshLock = "fileshare-portal-refresh"

RefreshLock is the name of the lock every UI of a portal takes around a refresh (WebLocks(RefreshLock) in a browser). It must be ONE name: the UIs a portal serves share its origin, so they share one session cookie and one refresh token, and a console tab and an explorer tab refreshing at once would spend that token twice.

const RequestHeader = "Portal-Request"

RequestHeader is the static header the portal requires of every call its pages make with fetch (its CSRF defence).

Variables

var (
	// ErrNotLoggedIn: there is no session, or it has ended -- log in again.
	ErrNotLoggedIn = errors.New("not logged in")
	// ErrTooLarge: a request body over the Doer's bound, refused before it
	// is sent.
	ErrTooLarge = errors.New("the request is larger than the portal takes")
)

Types

type Doer

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

Doer is the HTTP client of one server's requests through the portal.

func (*Doer) Do

func (d *Doer) Do(req *http.Request) (*http.Response, error)

Do sends req with the static header. When the portal answers that the server's token is missing or expiring (401, Portal-Refresh), it refreshes and sends it once more. Errors are ErrNotLoggedIn, ErrTooLarge, a *RefreshError, or the transport's. Any other answer is returned as it is -- a 401 without Portal-Refresh included: the portal saying nobody is logged in, or a server refusing its token, which the caller tells apart.

type Portal

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

Portal is a client of go-fileshare/portal.

func New

func New(base string, hc *http.Client, serialize func(func() error) error) *Portal

New is a client of the portal at base, an origin such as "https://files.example.org". serialize may be nil: refreshes are then serialized within this process only.

func (*Portal) Base

func (p *Portal) Base() string

Base is the portal's origin.

func (*Portal) Doer

func (p *Portal) Doer(server string, maxBody int64) *Doer

Doer is an HTTP client for server's requests -- /api/<server>/... for the admin API, /dav/<server>/... for its files -- with bodies of at most maxBody bytes, kept so that a request can be sent again after a refresh.

func (*Portal) EnsureToken

func (p *Portal) EnsureToken(ctx context.Context, server string) error

EnsureToken makes sure the session holds a current token for server -- before a download, which is a navigation: a navigation that meets "refresh first" cannot refresh and try again.

func (*Portal) LoginURL

func (p *Portal) LoginURL(returnTo string) string

LoginURL is the portal's login, coming back to returnTo (a path).

func (*Portal) Logout

func (p *Portal) Logout(ctx context.Context) (string, error)

Logout ends the session, and returns where the browser should go next to end it at the identity provider too ("" if nowhere).

func (*Portal) Session

func (p *Portal) Session(ctx context.Context) (*Session, error)

Session is who is logged in, or ErrNotLoggedIn.

type RefreshError

type RefreshError struct{ Status string }

RefreshError is a refresh the portal could not do -- the provider down, say -- which is not the end of the login.

func (*RefreshError) Error

func (e *RefreshError) Error() string

type Server

type Server struct {
	ID    string
	Label string
	// Reachable: its tokens come from the identity provider this session
	// logged in with.
	Reachable bool
	// DAV: the portal passes its WebDAV (/dav/<id>/...), so its files can be
	// browsed.
	DAV bool
}

A Server is one fileshare server the portal knows.

func (Server) Name

func (s Server) Name() string

Name is how a UI shows the server.

type Session

type Session struct {
	Issuer, Subject, Name string
	Expires               time.Time
	Servers               []Server
}

A Session is who is logged in, and which servers they can reach.

func (*Session) Who

func (s *Session) Who() string

Who is how a UI names the person.