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

    Constants

    This section is empty.

    Variables

    This section is empty.

    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(c context.Context, subscription string) error

              DeleteSubscription removes PubSub subscription if it exists.

              func (*AuthService) EnsureSubscription

              func (s *AuthService) EnsureSubscription(c 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(c context.Context) (int64, error)

                  GetLatestSnapshotRevision fetches revision number of the latest AuthDB snapshot.

                  func (*AuthService) GetSnapshot

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

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

                    func (*AuthService) ProcessPubSubPush

                    func (s *AuthService) ProcessPubSubPush(c 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(c 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(c 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(c 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.

                                Source Files

                                Directories

                                Path Synopsis