Handout #4 - Project 3

Updated 3/5/2002

• A lot of resources are available on-line and in the library. It is great to use these, but please always cite them in your projects.

Objective

In this project you will add dynamic activity to your site in the form of live auctions. The auction rules below are meant to be only a vague approximation of what happens in at Yahoo! and other real auction sites. The purpose being to implement something with interesting behavior, not to simulate reality.

Database tables & fields

You will have to augment the database tables from projects 1&2 slightly in order to implement the live auctions. The following two changes are required/recommended:

Users table: add a password field (required)

Auctions table: add a status field to indicate the status/outcome of the auction (recommended), e.g. active/sold/unsold, drop curBid and highBidder fields (suggested)

BidHistory table: add a bid id field as primary key. It is needed in the response to the /robots/newBid request.

Web pages

For this project you will need two sets of web pages that are almost identical in function but differ in presentation. The first set is a set of robot pages that will be used exclusively by the testing and benchmarking robot we are writing. These pages do not require any authentication and they return simple ascii text (content-type: text/plain) that can be parsed easily, i.e. no HTML. The second set is a set of user pages, through which a human user can see the information, i.e., what you would expect from a web site. The two main differences between these sets of pages are (1) the formatting of the content and (2) whether a "login" is required or not.

Robot pages

The following pages are for robots that submit items and bids and verify the operation of the auction market. For simplicity, these pages are not password protected. Each page must be of content-type text/plain (not HTML!), and consists of a table, one row per line, and each field separated by a comma. The fields must be in the order shown in the descriptions below.

• Date&time fields must be represented either as YYYY-MM-DD HH:MM:SS.S or in milliseconds since "the epoch"
• Prices are in whole dollars, i.e., "$100.00" gets represented simply as "100"

• Robot user page:
  • URL: /robots/user?userid
  • lists information about the user with the requested userid, this includes the static info (i.e. users table) as well as all auctions in which the user is involved
  • if the request is processed the server should return:
    • line 1: OK
    • line 2:  the static info with the following fields:
      • user id, user name, rating, numSells
    • lines 3+: show all auctions items in which the user is involved, one item per line
      • show items that the user is selling, has sold, has bid for, and has bought
      • fields for items sold: item id, status, buyQty, auctionQty, price, time
        • see below on what to show for status, buyQtyprice, auctionQty and time
      • fields for items bought: item id, status, qty, price, time
        • see below on what to show for status, qty and time
      • these lines must be sorted by time, from the oldest to the newest
  • if an error occurs the server should return:
    • line 1: ERROR
    • line 2: English explanation of the error, e.g., "USER NOT FOUND"
• Robot auction page:
  • URL: /robots/auction?auctionid
  • lists information about the auction with the requested auctionid, this includes the static info (i.e. auction table) as well as all bids placed on that item
  • if the request is processed the server should return:
    • line 1: OK
    • line 2: the static info with the following fields:
      • auctionid, name, seller id, buyPrice, qty, startPrice, increment, open, close time, location, imageUrl
      • the buyPrice should be reported as "null" if there is no buyPrice
      • the qty is the total (initial) quantity for sale
      • the imageUrl indicates where the image belonging to this auction can be fetched, if there is no image, return a url to an empty image or an image showing the text "no picture available"
    • line 3: status of the auction with the following fields:
      • status, buyQty, auctionQty, price, time
        • see below on what to show for status, price, qty and time
    • Additional lines must show all bids on the item
      • fields: bidid, userid, price, qty, time
      • these lines must be sorted by time, from the oldest to the newest
      • for each user, only show the most recent bid
  • if an error occurs the server should return:
    • line 1: ERROR
    • line 2: English explanation of the error, e.g., "AUCTION NOT FOUND"
• Robot new auction page: 
  • URL: /robots/newAuction?url-encoded-parameters
  • parameters: auction id, name, seller id, buyPrice, qty, startPrice, increment, location
  • a buyPrice of null indicates that there is no buyPrice
  • the auction id is the id to be assigned to the auction, and is guaranteed to be unique and >10000
  • example: /robots/newAuction?auctionid=10001&name=cool%20game&sellerid=tve&buyPrice=null&...
  • the auction start time is set to the time at which the auction is submitted, and the end time is determined by the standard auction duration set in the robots/init request (see below)
  • if the request is processed the server should return:
    • line 1: OK
    • line 2: auction id, start time, end time
  • if an error occurs the server should return:
    • line 1: ERROR
    • line 2: English explanation of the error
• Robot new image page: 
  • URL: /robots/newImage?auctionid
  • submits a new image in the body of the POST request for the item
  • the submitted content-type will be image/jpeg
  • if the request is processed the server should return:
    • line 1: OK
  • if an error occurs the server should return:
    • line 1: ERROR
    • line 2: English explanation of the error
• Robot new bid page: 
  • URL: /robots/newBid?url-encoded-parameters
  • parameters: auctionId, bidderId, price, qty
  • example: /robots/newAuction?price=100.50&bidderid=tve&...
  • if the request is processed the server should return:
    • line 1: OK
    • line 2: bid id
  • if an error occurs the server should return:
    • line 1: ERROR
    • line 2: English explanation of the error
• Robot initialization:
  • URL: /robots/init?duration=nnn
  • This request is a POST that creates a number of users, returns the database to its initial state and sets the auction duration
  • The database is returned to the state after loading the historical auctions from project 1. I.e. all auctions, bids, user additions,  etc. that occurred after February 1st 2002 must be removed
  • The duration for all auctions is encoded in the url parameters and is indicated in seconds; when the server starts (before the first init request), the duration is initialized to 5 minutes.
  • The post contains a list of users to be created (or initialized, if they already exist), one user per line
    • fields of the post: user id, user name, password, rating
  • if the request is processed the server should return:
    • line 1: OK
  • if an error occurs the server should return:
    • line 1: ERROR
    • line 2: English explanation of the error

Sample response for "GET /robots/user?tve":

HTTP/1.0 200 OK
Content-length: 238
Content-type: text/plain

OK
tve,Thorsten von Eicken,250,1
1043,bid,100,1,2002-02-01 08:30:05.0
1001,selling,0,0,2002-02-20 08:34:00.0

Sample response for "GET /robots/user?nobody":

HTTP/1.0 200 OK
Content-length: 16
Content-type: text/plain

ERROR
USER NOT FOUND

How to display information for auction/items being sold:

• fields: status, buyQty, auctionQty, price, time
• the buyQty shows the number of items sold at the buyPrice, these items are not counted in any of the steps below
• if no bid has been placed and the end time has been reached
  • status=unsold, auctionQty/price/time all show 0
• else-if no bid has been placed and the end time has not been reached
  • status=selling, auctionQty/price/time all show 0
• else-if at least one (non-buyPrice) bid has been placed and the end time has been reached
  • status=sold, auctionQty/price indicate the qty bought and the price, and time the end of the auction
• else (if at least one bid has been placed and the end time has not been reached)
  • status=selling, auctionQty/price indicate the qty and price as if the auction were to end now, and time the time of the last bid
• Important notes:
  • bids at the buyPrice (if any) are displayed using the buyQty field, the auctionQty/price/time fields only consider the "true auction" bids
  • the check for "end time has been reached" can be off by up to 30 seconds (in accordance with the "periodic check" in the "how to settle auctions" section below)

How to display information for bids (auction/items being bought):

• fields: status, qty, price, time
• if the bid is at (or above) the buyPrice
  • status=bought, price/qty indicate what the user bought, time is when the bid was placed
• else-if the end time has been reached and the bid was successful
  • status=bought, price/qty indicate what the user bought, time is when the bid was placed
• else (if the end time has not been reached or the bid was unsuccessful)
  • status=bid, price/qty indicate what the user bid, time is when the bid was placed
• Important notes:
  • the check for "end time has been reached" can be off by up to 30 seconds (in accordance with the "periodic check" in the "how to settle auctions" section below)

User pages

Your site will feature the following pages for its users:

• Home page: same as in project 2, but augmented with additional login box
  • login box fields: user name, password, and "login" button
  • once a user is logged-in
    • you must track the user through all web pages
    • you must display the user name on each page the user visits
• Item page: same as in project 2, but augmented with the following info
  • Indicate clearly whether the auction is still running or whether it has closed
  • If the auction has closed, indicate clearly who got the item and at what price
  • If the person browsing the item is logged in, display a box to enter a new bid (qty & price) (i.e., the user must be logged-in to be able to submit a new bid)
• User page: same as in project 2, but augmented with the following info
  • For each auction in which the user is involved in, indicate clearly whether it has closed
  • For each closed selling auction, indicate clearly what the outcome price/qty is
  • For each closed buying auction, indicate clearly whether the user got the item or not, and if so, at what price
• Item search results page as in project 2
• User search results page as in project 2
• New item page: new page to submit a new item for auction
  • Same fields as the equivalent robots page
  • Allow the user to upload an image on this page, or provide a separate page to add the image similar to the robots new image page
  • The user must be logged-in to be able to submit a new item
• New user page: a page to create new user accounts, the exact functionality is up to you

Notes:

• You will need pages in addition to the above, especially for error handling

How to settle auctions

• When an item is entered for auction, the seller indicates the following:
  • qty: number of items for sale as part of this auction
  • buyPrice: price at which the item(s) can be bought immediately, i.e. without waiting for the end of the auction
  • startPrice: minimum price the seller is willing to accept
  • increment: price increment from one bid to the next
• When an item is entered for auction, the system computes the following:
  • Start time: date&time at which the item is entered
  • End time: date&time at which the auction is over, computed as start time + duration, where the duration is fixed in the init request and defaults to 5 minutes when the system first starts
• When a bid is placed, the seller indicates the following:
  • qty: number of items for which the bid holds
  • price: price at which the buyer is willing to buy the item
• When a bid is placed, the system determines the following:
  • bid id: must be a monotonically increasing integer that indicates the order in which bids are considered (see below)
  • bid time: time at which the bid is placed, if bid time > end time the bid is refused (even if the auction has not been closed yet because the system has not done its periodic check, see below)
  • bid validity: bid qty <= sell qty, bid price >= start price, bid price >= highest bid + increment
    • clearly "highest bid" is not the optimal choice in this formula, but it will work
  • if the bid price >= buy price, the auction for the qty bid is terminated and the bidder got the item(s) at the buy price (note that if sell qty > bid qty the auction is not over)
  • if the buyer had any previous bids on the item the new bid replaces all of them
    • if a user places a bid where bid price >= buy price, that user cannot place any additional bids on any remaining items
• Periodically (at least every 30 seconds), the system checks for closed auctions:
  • for each auction whose end time has arrived, the outcome is determined
  • for auctions with qty=1, the highest valid bid is determined and the corresponding bidder will have bought the item
  • for auctions with qty=N>1, the highest valid bids totalling at least qty N are determined and the items are sold at the price of the lowest bid, for example:
    • selling qty=10, startPrice=50
    • bid1: qty=2,price=120; bid2: qty=6,price=110; bid3: qty=10,price=100
    • the 10 items are sold at $100, bidder1 gets two items, bidder2 gets 6 items, bidder3 gets 2 items

Note on ordering constraints:

Bids have to be processed strictly according to the assigned bid id. So this must be a sequential process. However, there is some room for adjustment in assigning the bid id. A client can only observe three events: the time at which the HTTP request is sent (Treq), the time at which the HTTP response is received (Tresp), and the bid id that was assigned (Bid). The only invariants that the server must maintain are:

Tresp1 < Treq2  =>  Bid1 < Bid2
Bid1 < Bid2  =>  Treq1 < Tresp2

Note that the bid times are not required to have the same sequence as the bid ids, i.e., it is acceptable to have a bid with a lower id and another bid show a later time. This is so we don't have to rely on synchronized clock when running on multiple servers.

What to turn in

Write a "one page" project overview describing the overall structure of your code. Describe the presentation layer (using WebMacro?), the business logic, and the storage/DB layer. Any special features you are using? Special algorithms, tricks, etc? Any packages you found on the web that are useful?

What's coming next

Project 4 will have a very simple problem statement: run your web service on 3 machines at the same time, all using the same database on bugatti (4th machine). We will load-balance incoming requests round-robin to your 3 servers. Provide the best performance you can, and make your service resilient to server and machine failures (i.e. we will kill your processes and/or halt the machines).