Documentation
¶
Overview ¶
Package score changes users' scores. Every change is one conditional update (the balance can never go negative, whatever runs concurrently) plus a ledger entry in the same transaction (design 04 §5.2; Blessing Skin read, modified and wrote the score, so concurrent requests could overdraw it or earn twice, C03).
Index ¶
- Constants
- Variables
- func Apply(ctx context.Context, tx *ent.Client, c Change) (int64, error)
- func Last(ctx context.Context, tx *ent.Client, userID int64, ...) (*ent.ScoreEntry, error)
- func Lock(ctx context.Context, tx *ent.Client, userIDs ...int64) error
- func Net(ctx context.Context, tx *ent.Client, userID int64, refType, refID string, ...) (int64, error)
- func SettingDefs() []settings.Def
- func SignIn(ctx context.Context, client *ent.Client, userID int64, p SignPolicy, ...) (int64, int64, time.Time, error)
- type Change
- type Rates
- type SignPolicy
- type TooEarlyError
Constants ¶
const ( ReasonRegister = "register" ReasonTextureUpload = "texture.upload" ReasonPlayerCreate = "player.create" ReasonPlayerDelete = "player.delete" // the refund of player.create ReasonAdmin = "admin" // an administrator set the score ReasonClosetAdd = "closet.add" ReasonClosetRemove = "closet.remove" // the refund of closet.add ReasonLikeAward = "texture.like" // the uploader's award for a closet add ReasonLikeTakeBack = "texture.unlike" // taking that award back ReasonVisibility = "texture.visibility" // switching public and private ReasonTextureDelete = "texture.delete" // giving back what an upload cost ReasonReportSubmit = "report.submit" // the reporter_modification for a report ReasonReportRefund = "report.refund" // giving a report.submit charge back ReasonReportReject = "report.reject" // taking a report.submit reward back ReasonReportReward = "report.reward" // the reward for an upheld report )
Reasons recorded in the ledger.
const MaxRate = 1_000_000
MaxRate bounds every score rate: a rate times the KB of the largest upload, or a sum of awards, then stays far from int64 overflow (which would turn a cost into a gain).
const ReasonSignIn = "sign_in"
ReasonSignIn is the ledger reason of a daily check-in.
Variables ¶
var ErrInsufficient = errors.New("not enough score")
ErrInsufficient means the user's score does not cover a negative delta.
Functions ¶
func Apply ¶
Apply changes a score inside tx and returns the new balance. A negative delta the balance does not cover fails with ErrInsufficient and changes nothing. A zero delta (a free upload, say) writes no ledger entry.
func Last ¶
func Last(ctx context.Context, tx *ent.Client, userID int64, reason, refType, refID string) (*ent.ScoreEntry, error)
Last returns the user's newest ledger entry with reason about ref (nil if none): what a refund reverses, instead of recomputing a price from today's settings.
func Lock ¶
Lock takes the row locks of the users a transaction will change, for the rest of tx, in ascending id order. Transactions that change scores take their locks in one order, before any other write: a texture first (texture.Lock), then these users. Two transactions that each lock one row and then want the other's cannot then exist, on any database. Without it:
- on MySQL, inserting a row that references a user takes a shared lock on the user's row (the foreign-key check; so does waiting on a duplicate unique key), and two such transactions that then change the score both wait for the other's shared lock (Error 1213);
- everywhere, two transactions that change two users' scores in opposite orders (two people adding each other's textures) wait for each other.
func Net ¶
func Net(ctx context.Context, tx *ent.Client, userID int64, refType, refID string, reasons ...string) (int64, error)
Net sums the user's ledger deltas about ref with any of reasons.
func SettingDefs ¶
SettingDefs are the score rates (Blessing Skin equivalents in docs/design/01 §5.5). score.initial belongs to registration (internal/account).
func SignIn ¶
func SignIn(ctx context.Context, client *ent.Client, userID int64, p SignPolicy, now time.Time, hooks ...*hook.Bus) (int64, int64, time.Time, error)
SignIn checks a user in: a random score between Min and Max, at most once per period. The period is enforced by one conditional update of users.last_sign_at, so concurrent check-ins earn once (Blessing Skin read, compared and wrote it, C03). It returns what was earned, the new balance and the next check-in time.
Types ¶
type Change ¶
type Change struct {
UserID int64
Delta int64
Reason string
// RefType and RefID name what the change is about, e.g. "texture" and "42".
RefType string
RefID string
Actor *int64 // the administrator making it; nil for the user or the system
Hooks *hook.Bus // optional; when non-nil and listening, publishes score.changed in tx
}
Change is one score change.
type Rates ¶
type Rates struct {
PerStorage, PrivatePerStorage, PerClosetItem, AwardPerTexture int64
PerPlayer, AwardPerLike int64
ReporterModification, ReporterReward int64
ReturnOnDelete bool
}
Rates are the score settings in effect.
func (Rates) UploadCost ¶
UploadCost is what an upload of size bytes costs: every started KB at the public or private rate, plus a closet item, minus the award, which only public textures earn (Blessing Skin also awarded private uploads, then took the award back when a texture went private and never returned it, C12). It can be negative: a gain.
type SignPolicy ¶
type SignPolicy struct {
Min, Max int64
Gap time.Duration // after the last check-in (when not Daily)
Daily bool // once per calendar day instead, in Location
Location *time.Location // the site's time zone
}
SignPolicy is how check-ins work on the site.
func SignPolicyFrom ¶
func SignPolicyFrom(s *settings.Snapshot) SignPolicy
SignPolicyFrom reads the check-in settings from a snapshot.
type TooEarlyError ¶
TooEarlyError means the user already checked in for now; Next is when they can again.
func (*TooEarlyError) Error ¶
func (e *TooEarlyError) Error() string