score

package
v1.1.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 19, 2026 License: MIT Imports: 12 Imported by: 0

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

View Source
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.

View Source
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).

View Source
const ReasonSignIn = "sign_in"

ReasonSignIn is the ledger reason of a daily check-in.

Variables

View Source
var ErrInsufficient = errors.New("not enough score")

ErrInsufficient means the user's score does not cover a negative delta.

Functions

func Apply

func Apply(ctx context.Context, tx *ent.Client, c Change) (int64, error)

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

func Lock(ctx context.Context, tx *ent.Client, userIDs ...int64) error

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

func SettingDefs() []settings.Def

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 RatesFrom

func RatesFrom(s *settings.Snapshot) Rates

RatesFrom reads the rates from a settings snapshot.

func (Rates) UploadCost

func (r Rates) UploadCost(size int64, public bool) int64

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.

func (SignPolicy) Next

func (p SignPolicy) Next(last *time.Time) time.Time

Next is when a user who last checked in at last can check in again (zero: now).

type TooEarlyError

type TooEarlyError struct{ Next time.Time }

TooEarlyError means the user already checked in for now; Next is when they can again.

func (*TooEarlyError) Error

func (e *TooEarlyError) Error() string

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL