How it works

The rules

• Bids are accepted only while the auction is live and server time is before ends_at. The current leader cannot bid again.
• Amounts are integer cents. The first bid must meet the starting price; later bids must meet the current price plus its increment.
• The maximum bid is the minimum next bid plus 100 increments, capped at $1,000,000.00.
• Soft close: a bid in the last 10 seconds moves the close to 30 seconds from now, up to 20 times. After the cap, bids are still accepted before the deadline but do not extend it.
• The winner has 180 seconds to pay. Payment is simulated; no money moves. A missed payment records one strike but never blocks bidding.
• If the winner does not pay, the runner-up gets an offer at their own highest bid and a fresh 180-second window. Without a runner-up, the lot is unsold. If the runner-up does not pay, the lot is unsold with no strike.

Auction lifecycle

Why two bids can't both win

Every bid calls one PostgreSQL function, place_bid, in its own transaction. The first thing it does is lock the auction row with SELECT … FOR UPDATE. A second bid on the same auction waits at that line until the first one commits.

Only after it holds the lock does the function read the clock and the current price. So every bid is checked against the latest committed state, and the time check uses the moment the bid actually got its turn.

Read Committed isolation is enough here because each statement after the lock sees the newest committed data, and the lock makes the check and the write one atomic step. The version column is a second guard: the update only succeeds if the version is still the one the function read.

Retries are safe because each request carries an idempotency key. The key and the original result are stored in the same transaction as the bid, so a retry returns the stored result.

Closing happens in the same function: a bid that arrives after the deadline closes the auction and is rejected. A scheduled job closes auctions nobody touches.

select * into v_auction from bidlock.auctions
 where id = p_auction_id for update;
v_now := bidlock.bidlock_now();
select * into v_prev from bidlock.bid_requests r
 where r.bidder_id = p_bidder_id and r.idempotency_key = p_idempotency_key;
-- Existing key: return stored result, or IDEMPOTENCY_MISMATCH.
v_auction := bidlock.advance_auction_locked(v_auction, v_now);
v_min := bidlock.min_next_bid(v_auction.starting_price, v_auction.current_price);
v_max := bidlock.max_bid(v_auction.starting_price, v_auction.current_price);
-- Validate status, deadline, leader, minimum and maximum; store rejections.
-- Apply soft close and store the accepted request/result in this transaction.
insert into bidlock.bids (...) values (...);
update bidlock.auctions set current_price = p_amount,
 leader_bidder_id = p_bidder_id, version = version + 1, ...
 where id = p_auction_id and version = v_auction.version;

Benchmark

The p95 latency target was not met: 269.23 ms against a 250 ms target. p99 was 329.69 ms against a 600 ms target. Unexpected errors: 0. Invariant violations: 0.

This test runs weekly on GitHub Actions against a production build in Docker Compose. It never runs against this site.

Right now

Bids today: 16 · Active sandboxes: 0 · Public lots today: 7

Updated 0 s ago.

Run it yourself

pnpm install
pnpm db:up
pnpm test:all
pnpm load:local