service

Documentation

Overview

Package service implements a wrapper around API exposed by auth_service: https://github.com/luci/luci-py/tree/master/appengine/auth_service

The main focus is AuthDB replication protocol used to propagate changes to database of groups.

Index

• func DeflateAuthDB(msg *protocol.AuthDB) ([]byte, error)
• func InflateAuthDB(blob []byte) (*protocol.AuthDB, error)
• type AuthDBAccess
• type AuthService
  • func (s *AuthService) DeleteSubscription(ctx context.Context, subscription string) error
  • func (s *AuthService) EnsureSubscription(ctx context.Context, subscription, pushURL string) error
  • func (s *AuthService) GetLatestSnapshotRevision(ctx context.Context) (int64, error)
  • func (s *AuthService) GetSnapshot(ctx context.Context, rev int64) (*Snapshot, error)
  • func (s *AuthService) ProcessPubSubPush(ctx context.Context, body []byte) (*Notification, error)
  • func (s *AuthService) PullPubSub(ctx context.Context, subscription string) (*Notification, error)
  • func (s *AuthService) RequestAccess(ctx context.Context) (*AuthDBAccess, error)
• type Notification
  • func (n *Notification) Acknowledge(ctx context.Context) error
• type Snapshot

Functions

func DeflateAuthDB

func DeflateAuthDB(msg *protocol.AuthDB) ([]byte, error)

DeflateAuthDB serializes AuthDB to byte buffer and compresses it with zlib.

func InflateAuthDB

func InflateAuthDB(blob []byte) (*protocol.AuthDB, error)

InflateAuthDB is reverse of DeflateAuthDB. It decompresses and deserializes AuthDB message.

Types

type AuthDBAccess

type AuthDBAccess struct {
	NotificationTopic string // pubsub topic name "project/<project>/topics/<topic>"
	StorageDumpPath   string // GCS storage path "<bucket>/<object>", may be empty
}

AuthDBAccess describes how an authorized reader can access the AuthDB.

See RequestAccess.

type AuthService

type AuthService struct {
	// URL is root URL (with protocol) of auth_service (e.g. "https://<host>").
	URL string
	// OAuthScopes is scopes to use for authentication (or nil for defaults).
	OAuthScopes []string
	// contains filtered or unexported fields
}

AuthService represents API exposed by auth_service.

It is a fairy low-level API, you must have good reasons for using it.

func (*AuthService) DeleteSubscription

func (s *AuthService) DeleteSubscription(ctx context.Context, subscription string) error

DeleteSubscription removes PubSub subscription if it exists.

func (*AuthService) EnsureSubscription

func (s *AuthService) EnsureSubscription(ctx context.Context, subscription, pushURL string) error

EnsureSubscription creates a new subscription to AuthDB change notifications topic or changes its pushURL if it already exists. `subscription` is full subscription name e.g. "projects/<projectid>/subscriptions/<subid>". Name of the topic is fetched from the auth service. Returns nil if such subscription already exists.

func (*AuthService) GetLatestSnapshotRevision

func (s *AuthService) GetLatestSnapshotRevision(ctx context.Context) (int64, error)

GetLatestSnapshotRevision fetches revision number of the latest AuthDB snapshot.

func (*AuthService) GetSnapshot

func (s *AuthService) GetSnapshot(ctx context.Context, rev int64) (*Snapshot, error)

GetSnapshot fetches AuthDB snapshot at given revision, unpacks and validates it.

func (*AuthService) ProcessPubSubPush

func (s *AuthService) ProcessPubSubPush(ctx context.Context, body []byte) (*Notification, error)

ProcessPubSubPush handles incoming PubSub push notification. `body` is the entire body of the push HTTP request. Invalid messages are silently skipped by returning nil error (to avoid redelivery). The error is still logged though.

func (*AuthService) PullPubSub

func (s *AuthService) PullPubSub(ctx context.Context, subscription string) (*Notification, error)

PullPubSub pulls pending PubSub messages (from subscription created previously by EnsureSubscription), authenticates them, and converts them into Notification object. Returns (nil, nil) if no pending messages. Does not wait for messages to arrive.

func (*AuthService) RequestAccess

func (s *AuthService) RequestAccess(ctx context.Context) (*AuthDBAccess, error)

RequestAccess asks Auth Service to grant the caller (us) access to the AuthDB change notifications PubSub topic and AuthDB GCS dump.

This works only if the caller is in "auth-trusted-services" group. As soon as the caller is removed from this group, the access is revoked.

type Notification

type Notification struct {
	Revision int64 // new auth DB revision
	// contains filtered or unexported fields
}

Notification represents a notification about AuthDB change. Must be acked once processed.

func (*Notification) Acknowledge

func (n *Notification) Acknowledge(ctx context.Context) error

Acknowledge tells PubSub to stop redelivering this notification.

type Snapshot

type Snapshot struct {
	AuthDB         *protocol.AuthDB
	AuthServiceURL string
	Rev            int64
	Created        time.Time
}

Snapshot contains AuthDB proto message (all user groups and other information received from auth_service), along with its revision number, timestamp of when it was created, and URL of a service it was fetched from.