Contest Data Server 2015

From ICPC-Contest Control Standard
Revision as of 17:09, 8 March 2016 by Deboer (talk | contribs) (Created page with "= Introduction to this DRAFT/working document = '''This article is DRAFT!!''' That means that at any time anything in this article, especially in the details, could chang...")
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to navigationJump to search

Introduction to this DRAFT/working document

This article is DRAFT!!

That means that at any time anything in this article, especially in the details, could change and likely will.

At this point this document is being updated by the SysOps CDS workgroup and is likely to change.

Change include but are not limited to:

  1. the URLs
  2. which services will and will not be serviced by the 2015 version of the CDS.
  3. everything else

The CDS (Services) Specification 1.0 will be formally published and distributed. This article is not that specification.


The Contest Data Server (or CDS) is a single place for clients of any kind to request contest data via URL. This document contains information on what services (URLs) are available from the CDS, what content is returned, and links to specs for the format of some files.

Internally, the CDS may be implemented using multiple servers, pull data from the contest control system or other servers, or even aggregate. From a client perspective the important thing is that none of this matters: the CDS is a one-stop shop for all contest information. Clients only need to know how to connect to URLs.

It's best to think of the CDS as an aggregator and gate keeper. There will be extensions that plug onto the CDS and provide new content or convert formats, but these are more like applications hosted by/within the CDS.

Why do we need a CDS?

We've run many finals without a CDS, so why do we need one now? Using a CDS has several advantages:

  • Standard-based: Regular HTTP access to everything.
  • Consistency: Similar URLs and formats where it makes sense.
  • Simplicity: A one stop shop for clients. A single root URL and access request for multiple services.
  • Data: Access to new data like team logos & pictures, contest images, etc.
  • Security: HTTPS and single point of control.
  • Caching: Reduced load on contest control and other systems.
  • Robustness: Clients no longer connect directly to critical contest systems.

There are also some benefits we can take advantage of in the future:

  • Scale: Architecture allows us to use an HTTP server and scale out to handle load.
  • Robustness: Fail-over with multiple CDS servers. Handle DOS attacks.

Implementation Notes

  • URLs below are in the format "http://cds/xyz". The exact hostname or IP address for 'cds' each year will be provided once the network is setup onsite.
  • Some of the URL contain a year (e.g. http://cds/2014/xyz") to indicate that these are temporary formats that will almost definitely change over the following year.
  • Invalid URLs, parameters (e.g. teamNum=500), or missing images will return the standard HTTP status code 404.

Access & Authentication

Requests for access to the CDS must be made through the world finals technical director (John Clevenger) and must include contact information for during the finals. Many of the services will contain private information, so each client will be given a unique user id & password to connect to the CDS. Access to all secure services is via HTTPS. (HTTP access will be redirected)

To simplify security, access is provided via roles that each have access to different content. The defined roles are as follows:

  • Public - Access only to data/services that are public contest info and can be shared externally at any time. These few services require no authentication.
  • Authorized - Authorized access to public data/services that can be shared externally at any time.
  • Analyst - Authorized + access to team backups and submission source.
  • Balloon - Authorized + access to runs within the last hour if the team has less than 3 balloons.
  • Blue - Full access to all data/services, typically someone within the contest network. (e.g. results during final hour)
  • Admin - Full access + control authority.

Access builds somewhat logically, e.g. Blue users have access to everything that Analysts & Balloon have. The services below are marked with what access role is required.

Contest Security Contest Data


The following section describes all of the services that are available through the CDS.


Contest Configuration


Access: Authorized

Access to contest configuration files as specified in the CCS spec Contest Control System.

todo: potentially figure out how to pack up all problem files in archive and serve that to a client


Team University Logos


Access: Authorized

Returns a png image 600x600 or smaller of the given team's University logo.

Team Photos


Access: Authorized

Returns a full HD (1920x1080) jpeg photo of the given team, typically taken during registration.

Team Overlay Images


Access: Authorized

Returns a full HD (1920x1080) png containing the team logo and name, for use as an overlay graphic.

The logo is in a rectangle that is 230x230 pixels, with the upper left corner of the rectangle located at 95 pixels from the left side and 795 pixels down from the top of the PNG image. The team name is in the ICPC font (Helvetica) in a rectangle that is 1275x230 pixels (width x height), with the upper left corner of the rectangle at 370 pixels from the left side and 795 pixels down from the top of the PNG image. Either graphic may or may not fill its entire rectangle.

A sample overlay file is provided here: Media:28.png.

Data Feeds

Contest Control System Event Feed


Access: Authorized

Returns the 2014 event feed as generated by the CCS: Event Feed 2014.

Clients without Blue access rights will receive a filtered event feed not containing submission judgments from the final hour.

Contest Feed Proposal


Access: Authorized

Returns a stream similar to the event feed, but merged with contest data from multiple sources: yamls, tsv, etc. Also supports filters/queries & JSON. Use at your own risk - this feed is being used to test future options.

Contest Control System JSON Scoreboard


Access: Authorized

Returns a JSON scoreboard as defined here: JSON Scoreboard 2014

Clients without sufficient access rights will received a filtered scoreboard that does not contain submission judgments from the final hour.

Contest RSS Feed (Draft)


Access: Authorized

Returns an RSS feed of solved submissions, e.g. "University of X solved problem Y!"

Clients without sufficient access rights will received a filtered RSS feed that does not contain submission judgments from the final hour.


Team Webcam Stream


Access: Public

Returns a video stream from the camera at the given team's workstation.

  • Video container: MPEG-TS
  • Video codec: H.264

Team Desktop Stream


Access: Public

Returns a video stream of the given team's desktop.

  • Video container: MPEG-TS
  • Video codec: H.264


Channels are a paired camera & screen video that can be changed on demand. It allows a client to use a fixed url for the duration of the contest, and for another user (typically an analyst) to switch which team the client is watching.


Access: Public

Returns video streams of the given channel, with content and format identical to the team webcam and desktop streams above.


Access: Analyst

Changes the given channel to output from the given team.

Reaction Videos


Access: Authorized

Returns a camera recording of the team for the given submission. Each video is X seconds long. Returns a 404 if the submission id is invalid or the video was not finished recording.

  • Video container: MPEG-TS
  • Video codec: H.264


Submission Source


Access: Analyst

Returns the source files for a team submission given a submission id.

Team backup files


Access: Analyst

Returns an archive (.tar.gz) with backup files from a Team's machine.

Start Time


Access: Blue

Allows the contest director to control the contest start time.