Documentation

Overview

    Package model is a model abstraction of publish.

    Package model is a model abstraction for health authority telemetry.

    Index

    Constants

    View Source
    const (
    	// StatsMaxOldestTEK represents the oldest age (days) that will be reflected in stats.
    	// Anything >= will count in the largest bucket.
    	StatsMaxOldestTEK = 15
    	// StatsMaxOnsetDays represents the oldest symptom onset age that will be reflected in stats.
    	// Anything >= will count in the largest bucket.
    	StatsMaxOnsetDays = 29
    
    	PlatformAndroid = "android"
    	PlatformIOS     = "ios"
    	PlatformUnknown = "unknown"
    )

    Variables

    View Source
    var (
    	// ErrorExposureKeyMismatch - internal coding error, tried to revise key A by passing in key B
    	ErrorExposureKeyMismatch = fmt.Errorf("attempted to revise a key with a different key")
    	// ErrorNonLocalProvenance - key revision attempted on federated key, which is not allowed
    	ErrorNonLocalProvenance = fmt.Errorf("key not origionally uploaded to this server, cannot revise")
    	// ErrorNotSameFederationSource - if a key arrived by federation, it can only be be revised by the same query (same source)
    	ErrorNotSameFederationSource = fmt.Errorf("key cannot be revised by a different federation query")
    	// ErrorKeyAlreadyRevised - attempt to revise a key that has already been revised.
    	ErrorKeyAlreadyRevised = fmt.Errorf("key has already been revised and cannot be revised again")
    )

    Functions

    func DaysBetweenIntervals

    func DaysBetweenIntervals(a int32, b int32) int32

      DaysBetweenIntervals calculates the number of days between two start intervals. The intervals represent their start interval (UTC midnight). Partial days always round up.

      func IntervalNumber

      func IntervalNumber(t time.Time) int32

        IntervalNumber calculates the exposure notification system interval number based on the input time.

        func ReduceStats

        func ReduceStats(hourly []*HealthAuthorityStats, onlyBefore time.Time, dayThreshold int64) []*verifyapi.StatsDay

          ReduceStats takes hourly breakdowns and rolls them up to daily. The onlyBefore time indicates the cutoff point for inclusion. The dayThreshold indicates how many entries are needed to include a given day. Day boundaries are all in UTC.

          func ReportTypeTransmissionRisk

          func ReportTypeTransmissionRisk(reportType string, providedTR int) int

            ReportTypeTransmissionRisk will calculate the backfill, default Transmission Risk. If there is a provided transmission risk that is non-zero, that will be used, otherwise this mapping is used: * Confirmed Test -> 2 * Clinical Diagnosis -> 4 * Negative -> 6 See constants defined in pkg/api/v1alpha1/verification_types.go

            func TimeForIntervalNumber

            func TimeForIntervalNumber(interval int32) time.Time

              TimeForIntervalNumber returns the time at which a specific interval starts. The interval number * 600 (10m = 600s) is the corresponding unix timestamp.

              func TruncateWindow

              func TruncateWindow(t time.Time, d time.Duration) time.Time

                TruncateWindow truncates a time based on the size of the creation window.

                Types

                type ErrorKeyInvalidReportTypeTransition

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

                  ErrorKeyInvalidReportTypeTransition is an error returned when the TEK tried to move to an invalid state (e.g. positive -> likely).

                  func (*ErrorKeyInvalidReportTypeTransition) Error

                    Error implements error.

                    type ExportImportConfig

                    type ExportImportConfig struct {
                    	DefaultReportType         string
                    	BackfillSymptomOnset      bool
                    	BackfillSymptomOnsetValue int32
                    	MaxSymptomOnsetDays       int32
                    	AllowClinical             bool
                    	AllowRevoked              bool
                    }

                      ExportImportConfig represents the configuration for processing of export files from other systems and how they are imported into this server.

                      type Exposure

                      type Exposure struct {
                      	ExposureKey       []byte
                      	TransmissionRisk  int
                      	AppPackageName    string
                      	Regions           []string
                      	Traveler          bool
                      	IntervalNumber    int32
                      	IntervalCount     int32
                      	CreatedAt         time.Time
                      	LocalProvenance   bool
                      	FederationSyncID  int64
                      	FederationQueryID string
                      	// Export file based Federation
                      	ExportImportID      *int64
                      	ImportFileID        *int64
                      	RevisedImportFileID *int64
                      
                      	// These fields are nullable to maintain backwards compatibility with
                      	// older versions that predate their existence.
                      	HealthAuthorityID     *int64
                      	ReportType            string
                      	DaysSinceSymptomOnset *int32
                      
                      	// Fields to support key revision.
                      	RevisedReportType            *string
                      	RevisedAt                    *time.Time
                      	RevisedDaysSinceSymptomOnset *int32
                      	RevisedTransmissionRisk      *int
                      	// contains filtered or unexported fields
                      }

                        Exposure represents the record as stored in the database

                        func FromExportKey

                        func FromExportKey(key *export.TemporaryExposureKey, config *ExportImportConfig) (*Exposure, error)

                          FromExportKey is used to read a key from an export file and convert it back to the internal database format.

                          func ReviseKeys

                          func ReviseKeys(ctx context.Context, existing map[string]*Exposure, incoming []*Exposure) ([]*Exposure, error)

                            ReviseKeys takes a set of existing keys, and a list of keys currently being uploaded. Only keys that need to be revised or are being created for the first time are returned in the output set.

                            func TransformExposureKey

                            func TransformExposureKey(exposureKey verifyapi.ExposureKey, appPackageName string, uppercaseRegions []string, settings *KeyTransform) (*Exposure, error)

                              TransformExposureKey converts individual key data to an exposure entity. Validations during the transform include:

                              * exposure keys are exactly 16 bytes in length after base64 decoding * minInterval <= interval number +intervalCount <= maxInterval * MinIntervalCount <= interval count <= MaxIntervalCount

                              func (*Exposure) AddMissingRegions

                              func (e *Exposure) AddMissingRegions(regions []string)

                                AddMissingRegions will merge the input regions into the regions already on the exposure. Set union operation.

                                func (*Exposure) AdjustAndValidate

                                func (e *Exposure) AdjustAndValidate(settings *KeyTransform) error

                                  AdjustAndValidate both validates the kay and if necessary makes adjustments to the timing field (createdAt).

                                  func (*Exposure) ExposureKeyBase64

                                  func (e *Exposure) ExposureKeyBase64() string

                                    ExposureKeyBase64 returns the ExposureKey property base64 encoded.

                                    func (*Exposure) HasBeenRevised

                                    func (e *Exposure) HasBeenRevised() bool

                                      HasBeenRevised returns true if this key has been revised. This is indicated by the RevisedAt time not being nil.

                                      func (*Exposure) HasDaysSinceSymptomOnset

                                      func (e *Exposure) HasDaysSinceSymptomOnset() bool

                                        HasDaysSinceSymptomOnset returns true if the this key has the days since symptom onset field is et.

                                        func (*Exposure) HasHealthAuthorityID

                                        func (e *Exposure) HasHealthAuthorityID() bool

                                          HasHealthAuthorityID returns true if this Exposure has a health authority ID.

                                          func (*Exposure) Revise

                                          func (e *Exposure) Revise(in *Exposure) (bool, error)

                                            Revise updates the Revised fields of a key

                                            func (*Exposure) SetDaysSinceSymptomOnset

                                            func (e *Exposure) SetDaysSinceSymptomOnset(d int32)

                                              SetDaysSinceSymptomOnset sets the days since symptom onset field, possibly allocating a new pointer.

                                              func (*Exposure) SetHealthAuthorityID

                                              func (e *Exposure) SetHealthAuthorityID(haID int64)

                                                SetHealthAuthorityID assigned a health authority ID. Typically done during transform.

                                                func (*Exposure) SetRevisedAt

                                                func (e *Exposure) SetRevisedAt(t time.Time) error

                                                  SetRevisedAt will set the revision time on this Exposure. The RevisedAt timestamp can only be set once. Attempting to set it again will result in an error.

                                                  func (*Exposure) SetRevisedDaysSinceSymptomOnset

                                                  func (e *Exposure) SetRevisedDaysSinceSymptomOnset(d int32)

                                                    SetRevisedDaysSinceSymptomOnset will set the revised days since symptom onset.

                                                    func (*Exposure) SetRevisedReportType

                                                    func (e *Exposure) SetRevisedReportType(rt string)

                                                      SetRevisedReportType will set the revised report type.

                                                      func (*Exposure) SetRevisedTransmissionRisk

                                                      func (e *Exposure) SetRevisedTransmissionRisk(tr int)

                                                        SetRevisedTransmissionRisk will set the revised transmission risk.

                                                        type HealthAuthorityStats

                                                        type HealthAuthorityStats struct {
                                                        	HealthAuthorityID int64
                                                        	Hour              time.Time
                                                        	PublishCount      []int64
                                                        	TEKCount          int64
                                                        	RevisionCount     int64
                                                        	OldestTekDays     []int64
                                                        	OnsetAgeDays      []int64
                                                        	MissingOnset      int64
                                                        }

                                                          HealthAuthorityStats represents the raw metrics for an individual health authority for a given hour.

                                                          func InitHour

                                                          func InitHour(healthAuthorityID int64, hour time.Time) *HealthAuthorityStats

                                                            InitHour creates a HealthAuthorityStats record for specified hour.

                                                            func (*HealthAuthorityStats) AddPublish

                                                            func (has *HealthAuthorityStats) AddPublish(info *PublishInfo)

                                                              AddPublish increments the stats for a given hour. This should be called inside of a read-modify-write database transaction. The HealthAuthorityStats represents the current state in the database, and the PublishInfo provided is added to it.

                                                              The HealthAuthorityStats must be created by InitHour or may not be initialized correctly.

                                                              This method does not enforce that it is called in a transaction, it only applyes the in-memory logic.

                                                              type KeyTransform

                                                              type KeyTransform struct {
                                                              	MinStartInterval      int32
                                                              	MaxStartInterval      int32
                                                              	MaxEndInteral         int32
                                                              	CreatedAt             time.Time
                                                              	ReleaseStillValidKeys bool
                                                              	BatchWindow           time.Duration
                                                              }

                                                                KeyTransform represents the settings to apply when transforming an individual key on a publish request.

                                                                type PublishInfo

                                                                type PublishInfo struct {
                                                                	CreatedAt    time.Time
                                                                	Platform     string
                                                                	NumTEKs      int32
                                                                	Revision     bool
                                                                	OldestDays   int
                                                                	OnsetDaysAgo int
                                                                	MissingOnset bool
                                                                }

                                                                  PublishInfo is the paremeters to the AddPublish call

                                                                  type TransformPublishResult

                                                                  type TransformPublishResult struct {
                                                                  	Exposures   []*Exposure
                                                                  	PublishInfo *PublishInfo
                                                                  	Warnings    []string
                                                                  }

                                                                  type Transformer

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

                                                                    Transformer represents a configured Publish -> Exposure[] transformer.

                                                                    func NewTransformer

                                                                    func NewTransformer(config TransformerConfig) (*Transformer, error)

                                                                      NewTransformer creates a transformer for turning publish API requests into records for insertion into the database. On the call to TransformPublish all data is validated according to the transformer that is used.

                                                                      func (*Transformer) TransformPublish

                                                                      func (t *Transformer) TransformPublish(ctx context.Context, inData *verifyapi.Publish, regions []string, claims *verification.VerifiedClaims, batchTime time.Time) (*TransformPublishResult, error)

                                                                        TransformPublish converts incoming key data to a list of exposure entities. The data in the request is validated during the transform, including:

                                                                        * 0 exposure Keys in the requests * > Transformer.maxExposureKeys in the request

                                                                        The return params are the list of exposures, a list of warnings, and any errors that occur.

                                                                        type TransformerConfig

                                                                        type TransformerConfig interface {
                                                                        	MaxExposureKeys() uint
                                                                        	MaxSameDayKeys() uint
                                                                        	MaxIntervalStartAge() time.Duration
                                                                        	TruncateWindow() time.Duration
                                                                        	MaxSymptomOnsetDays() uint
                                                                        	MaxValidSymptomOnsetReportDays() uint
                                                                        	DefaultSymptomOnsetDaysAgo() uint
                                                                        	DebugReleaseSameDayKeys() bool
                                                                        }

                                                                          TransformerConfig defines the interface that is needed to configure a `Transformer`