Something went wrong. Try again.
A community based topic aggregation platform built on atproto
Something went wrong. Try again.
123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755package posts
import ( "context" "crypto/sha256" "encoding/hex" "encoding/json" "errors" "fmt" "log" "time"
"Coves/internal/core/aggregators" "Coves/internal/core/communities")
// admitPost: the single decision point for "may this submission become a post// in this community?" (docs/POSTS.md §4.1, §5.6, §8).//// It is extraction PLUS new policy, and §4.1 is blunt about which is which.// What CreatePost enforces today is community existence, a private-visibility// block for regular users, and aggregator authorization + the aggregator's own// hourly quota — nothing else. The service docstring's "membership/ban// validation" was aspirational: there is no ban lookup anywhere on the write// path, and no per-author rate limiting at all. Both arrive here.//// WHY A SEPARATE FUNCTION RATHER THAN MORE STEPS IN CreatePost. The same// decision has to be made from three places: the synchronous local-community// fast path (§4.2 step 4), the firehose consumer when a post for a community we// host arrives from someone else's PDS (§5.6), and the notify endpoint (§7).// A decision that lived inside CreatePost would be reachable only from the// first, so the other two would silently admit what the first refuses.
// ActorClass is what the CALLER has already established the submitter to be.//// It is an INPUT rather than something this decision derives, and that is the// whole point. Today's classification reads TRUSTED_AGGREGATOR_DIDS (falling// back to KAGI_AGGREGATOR_DID) out of the process environment inside CreatePost// (service.go step 3). A decision function that reached for os.Getenv itself// could not have its trusted-actor branch tested alongside t.Parallel — Go's// own testing package refuses t.Setenv there — and, worse, would hide "who is// trusted" from the call site of the security decision it governs.type ActorClass string
const ( // ActorUser is a person posting on their own behalf. Every check applies. ActorUser ActorClass = "user"
// ActorRegisteredAggregator is a service the AppView has indexed a // social.coves.aggregator.service declaration for. It is held to the // community's authorization record and to its OWN hourly quota // (aggregators.ValidateAggregatorPost), not to membership or visibility. ActorRegisteredAggregator ActorClass = "registered_aggregator"
// ActorTrustedAggregator is a service named in TRUSTED_AGGREGATOR_DIDS — // the temporary env-var mechanism that predates a real authorization // endpoint. It skips visibility, ban and authorization checks entirely, // which is the existing behaviour and is preserved deliberately. ActorTrustedAggregator ActorClass = "trusted_aggregator")
// AdmissionRequest is one submission, described in the terms the decision needs// and no others. There is no record and no blob here: admitPost runs BEFORE any// of that work, so that a refusal costs a lookup rather than an upload.type AdmissionRequest struct { // Actor is the class the caller resolved. See ActorClass. Actor ActorClass
// AuthorDID is the authenticated author. CreatePost has already proven it // matches the DID on the request; this decision trusts that. AuthorDID string
// Community is the at-identifier as the client sent it — a handle // (!gardening.communities.coves.social) or a DID. Resolving it is the // decision's first step, because a community that does not resolve is the // first thing that can refuse a submission. Community string
// Fingerprint identifies WHAT is being submitted: the hash of the canonical // record with createdAt and the client-typed community identifier removed, // and the supplied thumbnail URL folded in (see submissionFingerprint). It // is the dedupe key, and it must exclude the timestamp or every // resubmission of identical content would look new. Fingerprint string}
// AdmissionDecision is the answer: admitted, or refused with a code.//// A refusal is a VALUE rather than an error, matching AdmissionOutcome above// and the project's standing preference for error codes over booleans. The// caller has to translate the code into whatever its transport speaks — a// sentinel error for CreatePost, an admissions row for the firehose engine —// and a refusal returned as an error would push the second of those into the// dead-letter queue, which is meant to hold genuine failures.type AdmissionDecision struct { // Code is the reason for a refusal, and empty for an admission. Code DecisionCode
// Community is the resolved community, populated on admission so that // CreatePost does not fetch it a second time. It is the one piece of state // the decision has already paid for that its caller would otherwise re-buy. Community *communities.Community
// Reservation is the ledger row that was inserted for this submission. It // is present on admission and must be released if the PDS write that // follows fails — see SubmissionLedger. Reservation *SubmissionReservation
// DedupeBucket is the window index the reservation was taken in, reported // so the caller derives the post's record key from THE SAME bucket the // ledger deduped against (SubmissionRkey). // // Reading the clock a second time at the call site would work almost // always and fail exactly at a bucket boundary — the retry that crossed it // would aim at a different rkey than the ledger scoped it to, which is the // one case the deterministic key exists for. DedupeBucket int64
// Cause carries the underlying error behind a refusal, when there is one, // so the caller can wrap it and keep it matchable. // // The refusal case is aggregator authorization. The API boundary maps that // refusal through aggregators.IsUnauthorized and aggregators.IsRateLimited // (internal/api/handlers/post/errors.go), which are predicates over the // AGGREGATORS package's sentinels. Collapsing that error into a bare // DecisionCode would turn a 403 "stop asking" and a 429 "ask later" into // the same answer, and a well-behaved aggregator would retry a permanent // refusal forever. // // It is ALSO set on the decision returned alongside a non-nil error, which // is what keeps a decision that could not be made from reading as an // admission — see Admitted. Cause error}
// Admitted reports whether the submission may proceed.//// There are three states here, not two: admitted, refused with a code, and// NOT DECIDED — a lookup failed and nothing was concluded either way. The third// is why this is not simply `Code == ""`. An infrastructure failure must not be// dressed up as a policy code (the client would be told to stop retrying// something that will work in a second), so those returns carry an empty Code;// a bare code test would then read the zero value as an admission, which is the// most dangerous default available on a security decision. A decision is an// admission only when there is neither a refusal code nor a cause.//// There is still no separate `admitted` bool: two representations of one fact// drift, and the code is the one that has to be right.func (d AdmissionDecision) Admitted() bool { return d.Code == "" && d.Cause == nil }
// SubmissionReservation identifies the ledger row admitPost inserted for a// submission, so a caller whose subsequent PDS write failed can release it.type SubmissionReservation struct { ID int64}
// SubmissionLimits bounds what one author may submit to one community (§8).//// Every field is required. There is deliberately no "zero means unlimited"// reading: a quota that silently disappears when an environment variable is// missing is not a quota, so config.Validate refuses to start the process with// any of these unset.type SubmissionLimits struct { // MaxPerAuthorPerCommunity is how many submissions one author may have // admitted to one community inside Window. MaxPerAuthorPerCommunity int
// Window is the rolling window the quota is counted over, matching the // aggregator limiter's semantics (aggregators.RateLimitWindow): a COUNT of // ledger rows newer than now-Window, not a fixed bucket that empties on the // hour and lets an author spend twice across the boundary. Window time.Duration
// DedupeWindow is the width of the bucket that scopes dedupe uniqueness. // Without it the ledger's unique constraint would forbid an author from // ever reposting identical content again, which is a different and much // stronger policy than "do not accept the same thing twice right now". DedupeWindow time.Duration}
// Clock is the decision's only source of time.//// Injected rather than called directly so that window expiry is testable// without waiting for one: docs/TEST_ARCHITECTURE.md §3.3 records that// time.Sleep in a test fails the audit, and that a rate limiter's window is// crossed through an injected clock.type Clock func() time.Time
// CommunityLookup resolves an at-identifier and fetches the community behind// it. Satisfied by communities.Service.type CommunityLookup interface { // ResolveCommunityIdentifier turns a handle or a DID into a DID. ResolveCommunityIdentifier(ctx context.Context, identifier string) (string, error)
// GetByDID returns the indexed community. GetByDID(ctx context.Context, did string) (*communities.Community, error)}
// BanLookup answers whether an author is banned from a community, by returning// the membership row that carries the answer.//// It returns the whole membership rather than a bool so that the translation of// "no membership row" into "not banned" happens in ONE place — inside// admitPost, next to the comment that explains why an error is not the same// thing. Satisfied by communities.Service.type BanLookup interface { // GetMembership returns the author's membership of the community, or an // error wrapping communities.ErrMembershipNotFound when there is none. GetMembership(ctx context.Context, userDID, communityIdentifier string) (*communities.Membership, error)}
// AggregatorAuthorizer checks a registered aggregator's authorization and its// own quota. Satisfied by aggregators.Service.type AggregatorAuthorizer interface { ValidateAggregatorPost(ctx context.Context, aggregatorDID, communityDID string) error}
// ReserveSubmissionCommand is one row of the post_submissions ledger.type ReserveSubmissionCommand struct { AuthorDID string CommunityDID string
// Fingerprint is the content hash — see AdmissionRequest.Fingerprint. Fingerprint string
// DedupeBucket is the index of the DedupeWindow this submission falls in, // derived from the injected clock. It is part of the unique key, which is // what makes dedupe expire. DedupeBucket int64}
// SubmissionLedger records admitted submissions, and IS the dedupe gate.//// RESERVE-THEN-CONFIRM. The row goes in BEFORE the PDS write and is released if// that write fails. The alternative — record after a successful write — leaves// a window in which two concurrent identical submissions both pass the check// and both get written, which is precisely the double-tap this exists to stop.// A leaked reservation (process died between the insert and the release) costs// the author one quota slot until the window rolls; a missed one costs the// community a duplicate post. The asymmetry decides the direction.//// THE INSERT IS THE CHECK. Dedupe is not a SELECT followed by an INSERT: it is// the INSERT, with the unique constraint as the arbiter. A read-then-write// would reopen the same race under concurrency, and the database is the only// participant that can serialize it.type SubmissionLedger interface { // Reserve inserts the ledger row for a submission. A unique-constraint // violation means an identical submission is already recorded for this // window, and is reported as ErrDuplicateSubmission rather than as a driver // error — the caller has to tell "someone already posted this" apart from // "the database is unwell". Reserve(ctx context.Context, cmd ReserveSubmissionCommand) (SubmissionReservation, error)
// Release removes a reservation whose submission never became a post. It is // idempotent: releasing a row that is already gone is not an error, because // the caller reaches this path while already handling a failure and must // not be handed a second one. Release(ctx context.Context, reservation SubmissionReservation) error
// CountSince counts one author's submissions to one community at or after // `since` — the rolling-window quota query. CountSince(ctx context.Context, authorDID, communityDID string, since time.Time) (int, error)}
// AdmissionPolicy is the collaborator set the new §8 policy needs, over and// above what postService already holds.type AdmissionPolicy struct { Ledger SubmissionLedger Bans BanLookup Limits SubmissionLimits Now Clock}
// WithAdmissionPolicy supplies the ban check, dedupe and per-author rate limit// on CreatePost. It is not optional: NewPostService refuses to construct a// service without a complete policy (see mustCompleteAdmissionPolicy), because// a post service whose admission policy silently defaulted to no-ops would be// one whose ban check and quota do not exist and nothing says so.func WithAdmissionPolicy(policy AdmissionPolicy) PostServiceOption { return func(s *postService) { s.admission = &policy }}
// mustCompleteAdmissionPolicy is NewPostService's guard: a service may not be// constructed without a complete admission policy.//// It panics rather than returning an error, matching how this codebase treats// every other mandatory collaborator (aggregators.NewAPIKeyService,// blueskypost.NewService): a missing policy is a wiring bug that must stop the// process at startup, not a runtime condition to handle. The old alternative —// silently substituting a no-op ledger and ban lookup — is exactly how the// pre-§4.1 docstring came to claim "membership/ban validation" that had never// existed on the write path.//// Every limit must be positive for the same reason config.Validate enforces// it: a quota that silently disappears when a field is left zero is not a// quota. Tests that are not about admission opt out EXPLICITLY with// NewAllowAllAdmissionPolicyForTests.func mustCompleteAdmissionPolicy(policy *AdmissionPolicy) { switch { case policy == nil: panic("posts.NewPostService: an admission policy is required — wire posts.WithAdmissionPolicy " + "(cmd/server) or posts.NewAllowAllAdmissionPolicyForTests (fixtures that are not about admission)") case policy.Ledger == nil: panic("posts.NewPostService: AdmissionPolicy.Ledger cannot be nil") case policy.Bans == nil: panic("posts.NewPostService: AdmissionPolicy.Bans cannot be nil") case policy.Now == nil: panic("posts.NewPostService: AdmissionPolicy.Now cannot be nil") case policy.Limits.MaxPerAuthorPerCommunity <= 0: panic("posts.NewPostService: AdmissionPolicy.Limits.MaxPerAuthorPerCommunity must be positive") case policy.Limits.Window <= 0: panic("posts.NewPostService: AdmissionPolicy.Limits.Window must be positive") case policy.Limits.DedupeWindow <= 0: panic("posts.NewPostService: AdmissionPolicy.Limits.DedupeWindow must be positive") }}
// unmeteredLedger is the allow-all test policy's ledger: it reserves nothing,// so neither dedupe nor the per-author quota applies.//// It cannot silently disable a configured limiter — it is only ever reachable// through NewAllowAllAdmissionPolicyForTests, whose name is the warning.type unmeteredLedger struct{}
func (unmeteredLedger) Reserve(context.Context, ReserveSubmissionCommand) (SubmissionReservation, error) { return SubmissionReservation{}, nil}
func (unmeteredLedger) Release(context.Context, SubmissionReservation) error { return nil }
// CountSince answers zero, which admits: with no ledger there is nothing to// count, and refusing on an absent substrate would take a service that never// asked for a quota and stop it posting at all.func (unmeteredLedger) CountSince(context.Context, string, string, time.Time) (int, error) { return 0, nil}
// unenforcedBans is the allow-all test policy's ban lookup, answering the way// an author with no membership row does. It returns the sentinel rather than a// nil membership so that it travels the same branch a real absent row does —// the "no membership means not banned" translation stays in one place.type unenforcedBans struct{}
func (unenforcedBans) GetMembership(context.Context, string, string) (*communities.Membership, error) { return nil, communities.ErrMembershipNotFound}
// NewAllowAllAdmissionPolicyForTests is the explicit opt-out for TEST fixtures// whose subject is not admission: it admits everything an unconfigured service// used to — no ban rows to find, no dedupe, no per-author quota — while// community existence, visibility and aggregator authorization stay enforced.//// THE NAME IS THE CONTRACT: this must never be wired in production code.// cmd/server wires the real policy, and mustCompleteAdmissionPolicy exists// precisely so that forgetting to do so fails at startup instead of shipping a// post service whose §8 enforcement quietly does not exist. The limits are// real (and enormous) only because construction refuses non-positive ones; the// unmetered ledger never counts against them anyway.func NewAllowAllAdmissionPolicyForTests() AdmissionPolicy { return AdmissionPolicy{ Ledger: unmeteredLedger{}, Bans: unenforcedBans{}, Limits: SubmissionLimits{ MaxPerAuthorPerCommunity: 1 << 30, Window: time.Hour, DedupeWindow: time.Hour, }, Now: time.Now, }}
// admissionDeps assembles the decision's inputs from the service's// collaborators. s.admission is never nil or incomplete — NewPostService// refuses to construct without a complete policy — so this cannot silently// hand admitPost a missing ledger or clock.func (s *postService) admissionDeps() admissionDeps { return admissionDeps{ communities: s.communityService, bans: s.admission.Bans, aggregators: s.aggregatorService, ledger: s.admission.Ledger, limits: s.admission.Limits, now: s.admission.Now, }}
// refusalError translates a refusal into the sentinel the API boundary maps.//// The codes and the sentinels are separate vocabularies on purpose: a code is// what the admissions table stores and what a federated peer is told, while a// sentinel is what internal/api/handlers/post turns into a status. This is the// one place they meet.func refusalError(decision AdmissionDecision) error { switch decision.Code { case DecisionCommunityNotFound: return ErrCommunityNotFound case DecisionCommunityPrivate: // Unchanged from the pre-§8 behaviour: a private community answers the // same 403 to a member-less user it always did. return ErrNotAuthorized case DecisionAuthorBanned: return ErrBanned case DecisionAggregatorNotAuthorized: // The aggregators-package sentinel has to survive: the boundary tells a // permanent 403 from a retryable 429 by matching on it, and the wording // is the one CreatePost has always used. return fmt.Errorf("aggregator not authorized: %w", decision.Cause) case DecisionDuplicateSubmission: return ErrDuplicateSubmission case DecisionRateLimitExceeded: return ErrRateLimitExceeded default: // A code minted without a mapping. Answering with a bare 500 would be // wrong twice over — the submission WAS refused, and the operator would // have nothing to search for — so the code itself goes in the error. return fmt.Errorf("submission refused: %s", decision.Code) }}
// admissionDeps is everything admitPost reads, gathered so the decision is a// function of its arguments rather than of a service's field set.type admissionDeps struct { communities CommunityLookup bans BanLookup aggregators AggregatorAuthorizer ledger SubmissionLedger limits SubmissionLimits now Clock}
// admitPost decides whether one submission may become a post.//// CHECK ORDER — each step its own refusal, and the order is load-bearing://// 1. Community resolution. Nothing else can be evaluated against a community// that does not exist.//// 2. Private visibility, for regular users. A banned member of a PRIVATE// community is refused with DecisionCommunityPrivate, NOT with// DecisionAuthorBanned — the ban lookup is not even consulted. A private// community's moderation state is behind the same wall as its content, and// answering "you are banned" would confirm to an outsider both that the// community exists and that a moderator has acted on them.//// 3. Ban, for regular users in public communities. A membership row with no// ban, or NO membership row at all, is not a ban — that is the ordinary// case, since posting to a public community does not require joining it.// Any OTHER lookup error FAILS the request. Failing open here would turn a// Postgres blip into a global unban for its duration, which is the one// failure mode a ban check exists to prevent.//// 4. Aggregator authorization, for registered aggregators. Existing// semantics, existing sentinels, carried on the decision's Cause.//// 5. Dedupe, for EVERY actor class. An aggregator re-polling an RSS feed and// resubmitting an identical item is the canonical case, so exempting// trusted actors here would exempt the exact traffic the check is for.//// 6. Rate limit, for regular users only.//// DEDUPE BEFORE RATE LIMIT. A client whose response was lost retries; if the// retry burned quota, a flaky connection would rate-limit a user who posted// once. Dedupe recognises the retry for what it is and refuses it without// charging for it.//// TRUSTED AGGREGATORS skip 2, 3, 4 (existing behaviour) and also skip 6: they// have no submission limit today, and inventing one here would be a silent// production behaviour change smuggled in under a refactor. REGISTERED// aggregators skip 6 for a different reason — they are already governed by// their own hourly quota inside ValidateAggregatorPost (step 4), and applying// the new per-author limit as well would silently halve an authorized// aggregator's throughput.//// A REFUSAL CONSUMES NO QUOTA: no refusal leaves a ledger row behind, including// the rate-limit refusal itself, whose reservation is released before it// returns. Otherwise an author who kept retrying past their limit would extend// their own lockout indefinitely.//// A non-nil error means the decision could NOT be made — a lookup failed — and// is distinct from a refusal, which is a decision.func admitPost(ctx context.Context, deps admissionDeps, req AdmissionRequest) (AdmissionDecision, error) { decision, err := evaluateAdmissionPolicy(ctx, deps, req) if err != nil || !decision.Admitted() { return decision, err } return reserveSubmission(ctx, deps, req, decision.Community)}
// evaluateAdmissionPolicy is admitPost's steps 0-4: everything that decides// whether this author may post to this community AT ALL, and nothing that// reserves a slot for the attempt.//// THE SPLIT EXISTS FOR THE ACCEPTANCE ENGINE. §5.6's engine decides about a post// that ALREADY EXISTS — often one it has decided about before, arriving again// from an overlapping feed or a redrive — so it needs the policy and must not// have the reservation. Running the ledger insert there would charge an author's// quota for a firehose redelivery and then refuse the redecision as a duplicate// of the submission it is redeciding.//// On an admission it returns the resolved community and NOTHING else, so a// caller that goes on to reserve does so explicitly.func evaluateAdmissionPolicy(ctx context.Context, deps admissionDeps, req AdmissionRequest) (AdmissionDecision, error) { // 0. The actor class must be one this decision knows. It gates everything // below — including the trusted skip of visibility, ban and authorization — // so an unknown value must fail CLOSED before any lookup runs. Falling // through would hand the zero value (a caller that forgot to classify) the // widest privileges in the system. switch req.Actor { case ActorUser, ActorRegisteredAggregator, ActorTrustedAggregator: default: return undecided(fmt.Errorf("unknown actor class %q: the submission cannot be evaluated", req.Actor)) }
// 1. Community resolution. Two lookups — the at-identifier to a DID, then // the DID to the indexed row — and either failing to find it is the same // answer to the client. communityDID, err := deps.communities.ResolveCommunityIdentifier(ctx, req.Community) if err != nil { switch { case errors.Is(err, communities.ErrCommunityNotFound): return AdmissionDecision{Code: DecisionCommunityNotFound}, nil case communities.IsValidationError(err): // A malformed identifier is the client's mistake and has to reach // the boundary as one: a validation error becomes a 400 naming the // bad field, while an unclassified error becomes an opaque 500. return undecided(NewValidationError("community", err.Error())) default: return undecided(fmt.Errorf("failed to resolve community identifier: %w", err)) } }
community, err := deps.communities.GetByDID(ctx, communityDID) if err != nil { if errors.Is(err, communities.ErrCommunityNotFound) { return AdmissionDecision{Code: DecisionCommunityNotFound}, nil } return undecided(fmt.Errorf("failed to fetch community: %w", err)) }
if req.Actor == ActorUser { // 2. The privacy wall, and it stands ahead of the ban lookup rather // than beside it: moderation state must not be read at all for a // community the submitter cannot see. See the check-order note above. if community.Visibility == "private" { return AdmissionDecision{Code: DecisionCommunityPrivate}, nil }
// 3. The ban. Looked up against the RESOLVED DID — handles are mutable, // and a ban keyed to one stops applying the moment a community renames // itself. membership, err := deps.bans.GetMembership(ctx, req.AuthorDID, community.DID) switch { case errors.Is(err, communities.ErrMembershipNotFound): // A VALUE meaning "not banned". Posting in a public community has // never required joining it, so an absent row is the common case. case err != nil: // Fail closed. Treating an unreachable database as "not banned" // would turn a Postgres blip into a global unban for its duration. return undecided(fmt.Errorf("failed to look up community membership: %w", err)) case membership != nil && membership.IsBanned: return AdmissionDecision{Code: DecisionAuthorBanned}, nil } }
// 4. Aggregator authorization, which carries the aggregators-package // sentinel that caused it: the boundary tells 403 from 429 by matching on // it, and a bare code would have a well-behaved aggregator retry a // permanent refusal forever. // // Only the package's POLICY sentinels are refusals. ValidateAggregatorPost // also fails when its own lookups do (a wrapped driver error carrying no // sentinel), and that is an undecided infrastructure failure like any // other — dressing it as DecisionAggregatorNotAuthorized would mint a // permanent-sounding 403 out of a Postgres blip. if req.Actor == ActorRegisteredAggregator { if err := deps.aggregators.ValidateAggregatorPost(ctx, req.AuthorDID, community.DID); err != nil { if errors.Is(err, aggregators.ErrNotAuthorized) || errors.Is(err, aggregators.ErrRateLimitExceeded) { return AdmissionDecision{Code: DecisionAggregatorNotAuthorized, Cause: err}, nil } return undecided(fmt.Errorf("failed to validate aggregator post: %w", err)) } }
return AdmissionDecision{Community: community}, nil}
// reserveSubmission is admitPost's steps 5-6: the dedupe insert and the// rolling-window quota, both of which exist only for a NEW submission.//// They are one function rather than two because step 6 counts the row step 5// inserted — the reservation is on the ledger before the quota is measured, so// the limit is reached when the count EXCEEDS it — and every path out that is// not an admission has to hand the slot back.func reserveSubmission(ctx context.Context, deps admissionDeps, req AdmissionRequest, community *communities.Community) (AdmissionDecision, error) { // 5. Dedupe, for every actor class. The INSERT is the check: a unique // violation means an identical submission is already on the ledger for this // window. It runs ahead of the quota so that a client retrying after a lost // response is told its post already exists rather than told to slow down. now := deps.now() bucket := dedupeBucket(now, deps.limits.DedupeWindow) reservation, err := deps.ledger.Reserve(ctx, ReserveSubmissionCommand{ AuthorDID: req.AuthorDID, CommunityDID: community.DID, Fingerprint: req.Fingerprint, DedupeBucket: bucket, }) if err != nil { if errors.Is(err, ErrDuplicateSubmission) { return AdmissionDecision{Code: DecisionDuplicateSubmission}, nil } return undecided(fmt.Errorf("failed to reserve submission: %w", err)) }
// 6. The rolling-window quota, for regular users only. Aggregators are // metered by their own limiter (step 4) or, when trusted, not at all. // // The reservation is already on the ledger, so it is counted here — the // limit is reached when the count EXCEEDS it — and every path out of this // block that is not an admission has to hand the slot back. if req.Actor == ActorUser { count, err := deps.ledger.CountSince(ctx, req.AuthorDID, community.DID, now.Add(-deps.limits.Window)) if err != nil { releaseReservation(ctx, deps.ledger, reservation) return undecided(fmt.Errorf("failed to count recent submissions: %w", err)) } if count > deps.limits.MaxPerAuthorPerCommunity { releaseReservation(ctx, deps.ledger, reservation) return AdmissionDecision{Code: DecisionRateLimitExceeded}, nil } }
return AdmissionDecision{Community: community, Reservation: &reservation, DedupeBucket: bucket}, nil}
// undecided reports that the decision could NOT be made.//// The error is returned twice — as the error, and on the decision's Cause — and// the second copy is the load-bearing one: it is what makes Admitted() false// for a caller that inspects the value. Leaving the decision zero would have a// caller who checked the decision before the error read a database outage as// permission to post.func undecided(err error) (AdmissionDecision, error) { return AdmissionDecision{Cause: err}, err}
// releaseReservation gives back a slot the decision took and then declined to// use. The error is logged rather than returned: every caller reaches this// while already reporting a refusal or a failure, and replacing that answer// with a second one would hide the reason the submission was actually stopped.//// The release runs DETACHED from the caller's cancellation (precedent:// adminreports.raiseAlert), because the most common reason to be here at all// is that the caller's context is already dead — a client that disconnected// mid-write is exactly a failed PDS write. A release issued on that context// would be refused by Postgres as canceled too, and the reservation would// leak: one quota slot burned and the author's retry refused as a duplicate,// with nothing but a warning line to say why. Context values (trace IDs)// survive; only the cancellation signal is dropped, and the fresh timeout// keeps a wedged database from pinning the goroutine.func releaseReservation(ctx context.Context, ledger SubmissionLedger, reservation SubmissionReservation) { releaseCtx, cancel := context.WithTimeout(context.WithoutCancel(ctx), 5*time.Second) defer cancel()
if err := ledger.Release(releaseCtx, reservation); err != nil { log.Printf("[POST-ADMIT] Warning: failed to release submission reservation %d: %v", reservation.ID, err) }}
// dedupeBucket is the index of the window `now` falls in, so that two// submissions in the same window collide on the ledger's unique key and two// submissions a window apart do not.//// Buckets are aligned to the epoch, not to the submission, so the effective// dedupe protection ranges over (0, window] depending on where in the bucket// a submission lands: content submitted just before a bucket edge can be// resubmitted the moment the edge passes. That tradeoff is deliberate — the// epoch-aligned key self-expires without a sweeper, where a per-submission// window would need a range predicate or a cleanup process to expire. The// same boundary bounds a leaked reservation: a crash between Reserve and the// PDS write leaves a row that burns one quota slot and refuses identical// content as a duplicate until the bucket rolls, then heals on its own.func dedupeBucket(now time.Time, window time.Duration) int64 { // A non-positive window would divide by zero. config.Validate refuses to // start a process with one, so reaching this is a wiring bug rather than an // operator mistake; collapsing to a single bucket keeps it from panicking // on the write path, and the constant bucket makes the misconfiguration // loud (every repost is refused) rather than silent. if window <= 0 { return 0 } return now.UnixNano() / int64(window)}
// submissionFingerprint hashes what a moderator would judge about a// submission: everything on the record except createdAt and community, plus// the thumbnail URL that rides alongside the record.//// The timestamp has to go. It is stamped by the server at submission time// (service.go step 6), so it differs on every attempt — including the retry// after a lost response, which is the case dedupe exists to catch. A// fingerprint that included it would never match anything.//// The community field has to go too, for the opposite failure. It holds the// at-identifier as the CLIENT typed it — a handle one time, a DID the next —// while the ledger's unique key already scopes the fingerprint by the// RESOLVED community DID. Hashing the client-typed identifier would let the// same submission to the same community bypass dedupe simply by switching// spelling between attempts; leaving it out cannot collide submissions to// DIFFERENT communities, because the ledger key keeps them apart.//// The thumbnail URL is IN, even though it is not a record field: a trusted// aggregator supplies it alongside the record (CreatePostRequest.ThumbnailURL)// and it changes what readers ultimately see. Two submissions differing only// in their thumbnail are different posts, and excluding it would refuse the// second as a repeat of the first.//// IT STILL HASHES THE DEPRECATED PostRecord SHAPE, not the postv2 record that// is actually written. The two describe the same submission — every field a// CreatePostRequest can populate exists on both — so the fingerprint identifies// the same posts either way, and keeping this shape keeps every dedupe row// already on the ledger valid across the deploy that flips the write path.// Moving it onto PostV2Record is a TASK 8 change, not an outstanding cycle-2// one, and the milestone is chosen rather than deferred. Retyping repartitions// every live post_submissions row: an author mid-retry when the binary rolls// would miss their own reservation and be admitted as a second post, which is// the exact duplicate the deterministic rkey exists to close. Task 8// re-materializes these records anyway, so it is the one moment the change// costs nothing.func submissionFingerprint(record PostRecord, thumbnailURL *string) string { // The record is taken by value, so clearing fields here cannot affect the // record the caller goes on to write. record.CreatedAt = "" record.Community = ""
material := struct { Record PostRecord `json:"record"` ThumbnailURL *string `json:"thumbnailUrl,omitempty"` }{Record: record, ThumbnailURL: thumbnailURL}
canonical, err := json.Marshal(material) if err != nil { // Unreachable in practice: every field of a PostRecord either has a // concrete marshalable type or holds a value decoded from JSON. Hashing // a Go rendering instead of returning an empty string matters anyway — // a constant fingerprint would collide every submission with every // other, and the second post the instance ever received would be // refused as a repeat of the first. log.Printf("[POST-ADMIT] Warning: submission fingerprint fell back to a Go rendering, canonical JSON marshal failed: %v", err) canonical = []byte(fmt.Sprintf("%#v", material)) }
sum := sha256.Sum256(canonical) return hex.EncodeToString(sum[:])}