discovery

Documentation

Overview

Package discovery implements the server discovery by contacting disco.eduvpn.org and returning the data as a Go structure

Index

• Variables
• type Discovery
  • func (discovery *Discovery) Copy() (Discovery, error)
  • func (discovery *Discovery) DetermineOrganizationsUpdate() bool
  • func (discovery *Discovery) DetermineServersUpdate() bool
  • func (discovery *Discovery) MarkOrganizationsExpired()
  • func (discovery *Discovery) MarkServersExpired()
  • func (discovery *Discovery) Organizations(ctx context.Context) (*Organizations, bool, error)
  • func (discovery *Discovery) SecureHomeArgs(orgID string) (*Organization, *Server, error)
  • func (discovery *Discovery) SecureLocationList() []string
  • func (discovery *Discovery) ServerByCountryCode(countryCode string) (*Server, error)
  • func (discovery *Discovery) ServerByURL(baseURL string, srvType string) (*Server, error)
  • func (discovery *Discovery) Servers(ctx context.Context) (*Servers, bool, error)
  • func (discovery *Discovery) UpdateServers(other Discovery)
• type ErrCountryNotFound
  • func (cnf *ErrCountryNotFound) Error() string
• type Manager
  • func NewManager(disco *Discovery) *Manager
  • func (m *Manager) Cancel()
  • func (m *Manager) Discovery(write bool) (*Discovery, func())
  • func (m *Manager) Startup(ctx context.Context, cb func())
• type Organization
  • func (o *Organization) Score(search string) int
• type Organizations
• type Server
  • func (s *Server) Score(search string) int
• type Servers

Variables

var DiscoURL = "https://disco.eduvpn.org/v2/"

DiscoURL is the URL used for fetching the discovery files and signatures

var HasCache bool

HasCache denotes whether or not we have an embedded cache available

Types

type Discovery

type Discovery struct {

	// Organizations represents the organizations that are returned by the discovery server
	OrganizationList Organizations `json:"organizations"`

	// Servers represents the servers that are returned by the discovery server
	ServerList Servers `json:"servers"`
	// contains filtered or unexported fields
}

Discovery is the main structure used for this package.

func (*Discovery) Copy

func (discovery *Discovery) Copy() (Discovery, error)

func (*Discovery) DetermineOrganizationsUpdate

func (discovery *Discovery) DetermineOrganizationsUpdate() bool

DetermineOrganizationsUpdate returns a boolean indicating whether or not the discovery organizations should be updated https://github.com/eduvpn/documentation/blob/v3/SERVER_DISCOVERY.md - [IMPLEMENTED] on "first launch" when offering the search for "Institute Access" and "Organizations"; - [IMPLEMENTED in client/client.go and here] when the user tries to add new server AND the user did NOT yet choose an organization before; Implemented in Register() - [IMPLEMENTED in client/client.go] when the authorization for the server associated with an already chosen organization is triggered, e.g. after expiry or revocation. - [IMPLEMENTED here] NOTE: when the org_id that the user chose previously is no longer available in organization_list.json the application should ask the user to choose their organization (again). This can occur for example when the organization replaced their identity provider, uses a different domain after rebranding or simply ceased to exist.

func (*Discovery) DetermineServersUpdate

func (discovery *Discovery) DetermineServersUpdate() bool

DetermineServersUpdate returns whether or not the discovery servers should be updated by contacting the discovery server https://github.com/eduvpn/documentation/blob/v3/SERVER_DISCOVERY.md - [Implemented] The application MUST always fetch the server_list.json at application start. - The application MAY refresh the server_list.json periodically, e.g. once every hour.

func (*Discovery) MarkOrganizationsExpired

func (discovery *Discovery) MarkOrganizationsExpired()

MarkOrganizationsExpired marks the organizations as expired

func (*Discovery) MarkServersExpired

func (discovery *Discovery) MarkServersExpired()

MarkServersExpired marks the servers as expired

func (*Discovery) Organizations

func (discovery *Discovery) Organizations(ctx context.Context) (*Organizations, bool, error)

Organizations returns the discovery organizations The second return value is a boolean that indicates whether a fresh list was updated internally If there was an error, a cached copy is returned if available.

func (*Discovery) SecureHomeArgs

func (discovery *Discovery) SecureHomeArgs(orgID string) (*Organization, *Server, error)

SecureHomeArgs returns the secure internet home server arguments: - The organization it belongs to - The secure internet server itself An error is returned if and only if nil is returned for the organization.

func (*Discovery) SecureLocationList

func (discovery *Discovery) SecureLocationList() []string

SecureLocationList returns a slice of all the available locations.

func (*Discovery) ServerByCountryCode

func (discovery *Discovery) ServerByCountryCode(countryCode string) (*Server, error)

ServerByCountryCode returns the discovery server by the country code An error is returned if and only if nil is returned for the server.

func (*Discovery) ServerByURL

func (discovery *Discovery) ServerByURL(
	baseURL string,
	srvType string,
) (*Server, error)

ServerByURL returns the discovery server by the base URL and the according type ("secure_internet", "institute_access") An error is returned if and only if nil is returned for the server.

func (*Discovery) Servers

func (discovery *Discovery) Servers(ctx context.Context) (*Servers, bool, error)

Servers returns the discovery servers The second return value is a boolean that indicates whether a fresh list was updated internally If there was an error, a cached copy is returned if available.

func (*Discovery) UpdateServers

func (discovery *Discovery) UpdateServers(other Discovery)

type ErrCountryNotFound

type ErrCountryNotFound struct {
	CountryCode string
}

ErrCountryNotFound is used when the secure internet country cannot be found

func (*ErrCountryNotFound) Error

func (cnf *ErrCountryNotFound) Error() string

type Manager

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

func NewManager

func NewManager(disco *Discovery) *Manager

func (*Manager) Cancel

func (m *Manager) Cancel()

func (*Manager) Discovery

func (m *Manager) Discovery(write bool) (*Discovery, func())

func (*Manager) Startup

func (m *Manager) Startup(ctx context.Context, cb func())

type Organization

type Organization struct {
	// Organization is the embedded public type that is a subset of this thus common Organization
	discotypes.Organization
	// SecureInternetHome is the secure internet home server that belongs to this organization
	// Omitted if none is defined
	SecureInternetHome string `json:"secure_internet_home"`
	// KeywordList is the list of keywords
	// Omitted if none is defined
	KeywordList discotypes.MapOrString `json:"keyword_list,omitempty"`
}

Organization is a single discovery Organization

func (*Organization) Score

func (o *Organization) Score(search string) int

type Organizations

type Organizations struct {
	// Version is the version field in discovery. The Go library checks this for rollbacks
	Version uint64 `json:"v"`
	// List is the list of organizations, omitted if empty
	List []Organization `json:"organization_list,omitempty"`
	// Timestamp is the timestamp that is internally used by the Go library to keep track
	// of when the organizations were last updated
	Timestamp time.Time `json:"go_timestamp"`
	// UpdateHeader is the result of the "Last-Modified" header
	UpdateHeader time.Time `json:"go_update_header"`
}

Organizations are the list of organizations from https://disco.eduvpn.org/v2/organization_list.json

type Server

type Server struct {
	// Server is the embedded public type that is a subset of this common Server
	discotypes.Server
	// AuthenticationURLTemplate is the template to be used for authentication to skip WAYF
	AuthenticationURLTemplate string `json:"authentication_url_template,omitempty"`
	// KeywordList are the keywords of the server, omitted if empty
	KeywordList discotypes.MapOrString `json:"keyword_list,omitempty"`
	// PublicKeyList are the public keys of the server. Currently not used in this lib but returned by the upstream discovery server
	PublicKeyList []string `json:"public_key_list,omitempty"`
	// SupportContact is the list/slice of support contacts
	SupportContact []string `json:"support_contact,omitempty"`
}

Server is a single discovery server

func (*Server) Score

func (s *Server) Score(search string) int

Matches returns if the search query `str` matches with this server

type Servers

type Servers struct {
	// Version is the version field in discovery. The Go library checks this for rollbacks
	Version uint64 `json:"v"`
	// List is the list of servers, omitted if empty
	List []Server `json:"server_list,omitempty"`
	// Timestamp is a timestamp that is internally used by the Go library to keek track
	// of when the servers were last updated
	Timestamp time.Time `json:"go_timestamp"`
	// UpdateHeader is the result of the "Last-Modified" header
	UpdateHeader time.Time `json:"go_update_header"`
}

Servers are the list of servers from https://disco.eduvpn.org/v2/server_list.json