Documentation
¶
Overview ¶
Package connection is what connecting a GitHub organisation leaves behind, shared by the service that writes it and the controller that reads it.
Two objects, for the reason a workspace is two: the record and the credential have different readers. The RECORD — which App, installed where, connected when and by whom — is what the console shows. The CREDENTIAL is the App's private key, which only the controller acts with; it lives in one Secret the controller mounts as a volume, so the controller needs no permission to read Secrets through the API at all, and the service that wrote it reads it for one thing only: revoking the installation on Disconnect.
Index ¶
- Constants
- Variables
- func ConfigMapName(release string) string
- func ConfirmationKey(org string) string
- func EncodeConfirmation(c Confirmation) (string, error)
- func EncodeCredential(c Credential) ([]byte, error)
- func EncodePassRequest(r PassRequest) (string, error)
- func EncodeRecord(r Record) (string, error)
- func Key(org string) string
- func OrgOfKey(key string) (string, bool)
- func ParsePassKey(key string) (org string, ok bool)
- func PassKey(org string) string
- func SecretName(release string) string
- type Confirmation
- type ConfirmationStore
- type Credential
- type PassRequest
- type Record
- type Store
Constants ¶
const ConfirmationTTL = 24 * time.Hour
ConfirmationTTL is how long an operator's confirmation of a removal set holds. Long enough for the next pass; short enough that nobody finds a forgotten confirmation doing something weeks later.
const PassGap = rails.PassGap
PassGap is how soon after one request for a pass another is refused.
const Version = 1
Version is the document version this build writes and reads.
Variables ¶
var ErrVersion = errors.New("connection: unsupported document version")
ErrVersion is a document of a version this build does not read.
Functions ¶
func ConfigMapName ¶
ConfigMapName is the object holding every organisation's record.
func ConfirmationKey ¶
ConfirmationKey is where an organisation's confirmation is kept, beside its record. A leading underscore is never an organisation's login.
func EncodeConfirmation ¶
func EncodeConfirmation(c Confirmation) (string, error)
EncodeConfirmation writes a confirmation.
func EncodeCredential ¶
func EncodeCredential(c Credential) ([]byte, error)
EncodeCredential writes a credential.
func EncodePassRequest ¶
func EncodePassRequest(r PassRequest) (string, error)
EncodePassRequest writes a request.
func Key ¶
Key is where one organisation's document is kept, in either object. It is also the file name the controller reads it from.
func ParsePassKey ¶
ParsePassKey reads a pass request's organisation back out of a key.
func PassKey ¶
PassKey is where an operator's request for a pass now is kept, beside the records: `_pass.<org>.json`, one per organisation, replaced by each request. The controller never deletes it; it compares the request's time with the last one it acted on. A leading underscore is never an organisation's login.
func SecretName ¶
SecretName is the object holding every organisation's credential.
Types ¶
type Confirmation ¶
type Confirmation struct {
Version int `json:"version"`
Org string `json:"org"`
Fingerprint string `json:"fingerprint"`
By string `json:"by"`
At time.Time `json:"at"`
}
Confirmation is an operator's confirmation that one set of removals, over the limit, may go ahead.
func DecodeConfirmation ¶
func DecodeConfirmation(raw string) (Confirmation, error)
DecodeConfirmation reads a confirmation.
type ConfirmationStore ¶ added in v1.76.0
type ConfirmationStore interface {
PutConfirmation(ctx context.Context, confirmation Confirmation) error
Confirmations(ctx context.Context) (map[string]Confirmation, error)
}
ConfirmationStore is where operators' confirmations of removal sets are kept.
type Credential ¶
type Credential struct {
Version int `json:"version"`
Org string `json:"org"`
AppID int64 `json:"app_id"`
InstallationID int64 `json:"installation_id,omitempty"`
PrivateKey string `json:"private_key"`
// Record is a copy of the organisation's record, so that the Secret
// alone restores a connection whose ConfigMap is gone. The controller
// never reads it.
Record *Record `json:"record,omitempty"`
}
Credential is what the controller authenticates as, in one file.
func DecodeCredential ¶
func DecodeCredential(raw []byte) (Credential, error)
DecodeCredential reads a credential.
type PassRequest ¶
type PassRequest struct {
Version int `json:"version"`
Org string `json:"org"`
At time.Time `json:"at"`
By string `json:"by"`
}
PassRequest is an operator's request that the controller pass over an organisation now.
func DecodePassRequest ¶
func DecodePassRequest(raw string) (PassRequest, error)
DecodePassRequest reads a request.
type Record ¶
type Record struct {
Version int `json:"version"`
Org string `json:"org"`
AppID int64 `json:"app_id"`
AppSlug string `json:"app_slug"`
// InstallationID is zero between Create and Install: the owner made
// the App and has not installed it yet.
InstallationID int64 `json:"installation_id,omitempty"`
HTMLURL string `json:"html_url,omitempty"`
ConnectedAt time.Time `json:"connected_at"`
ConnectedBy string `json:"connected_by"`
// Owner is the directory workspace id that owns this organisation,
// chosen when it was connected: the workspace whose SCOPED operator
// (`<id>:access-roster:operator`) may operate it beside the
// installation-wide operator. Empty, only the installation-wide roles
// operate it. Only the installation-wide operator changes it
// afterwards. The field is optional in version 1, so a record written
// before it existed reads as "no owner" and behaves exactly as it did.
Owner string `json:"owner,omitempty"`
// AppRef is the id of the GitHub App this organisation uses (ADR 0072):
// the App's key is kept once, under the App, and the record holds only
// the installation and the organisation's own state. Empty is the
// organisation's own App, whose key is kept with the record; a record
// written before the field existed reads so.
AppRef string `json:"app_ref,omitempty"`
}
Record is one connected organisation, as the console shows it.
type Store ¶ added in v1.76.0
type Store interface {
Put(ctx context.Context, record Record, credential Credential) error
List(ctx context.Context) ([]Record, error)
Credential(ctx context.Context, org string) (Credential, bool, error)
// SetOwner changes only a record's owner, under the object's version;
// found is false when the organisation has no record.
SetOwner(ctx context.Context, org, owner string) (previous string, found bool, err error)
Delete(ctx context.Context, org string) error
// RequestPass keeps an operator's request for a pass now; kept is false,
// with when the last one was, if that is under PassGap old.
RequestPass(ctx context.Context, r PassRequest) (kept bool, last time.Time, err error)
// PassRequests reads every organisation's last request for a pass.
PassRequests(ctx context.Context) (map[string]PassRequest, error)
}
Store is where connected organisations are kept: a record the console shows, a credential only the controller acts with.
Source Files