diff --git a/CHANGELOG.md b/CHANGELOG.md index 018063a..2d1b23a 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -5,9 +5,13 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). ## [v4.1.0-pre] - Unreleased +### Fixed +- Clear Debug.summary field when making mothballs + ### Added - More log events - [Log channels document](docs/logs.md) +- More detailed [API documntation](docs/api.md) ## [v4.0.0] - 2020-10-14 ### Fixed diff --git a/docs/api.md b/docs/api.md index 517d2c2..948848a 100644 --- a/docs/api.md +++ b/docs/api.md @@ -27,7 +27,7 @@ Returns the current MOTH event state as a JSON object. ```json { "Config": { - "Devel": true/false + "Devel": false # true means this is a development server }, "Messages: "HTML to be rendered as broadcast messages", "TeamNames": { @@ -47,6 +47,51 @@ Returns the current MOTH event state as a JSON object. } ``` +#### Example HTTP transaction + +##### Request + +``` +GET /state HTTP/1.0 + +``` + +##### Response + +This response has been reflowed for readability: +an actual on-wire response would not have newlines or indentation. + +``` +HTTP/1.0 200 OK +Content-Type: application/json + +{"Config": + {"Devel":false}, + "Messages":"

Welcome to the event!

Event ends at 19:00!

", + "TeamNames":{ + "0":"Mike and Jack", + "12":"Team 2", + "4":"Team 8" + }, + "PointsLog":[ + [1602702696,"0","nocode",1], + [1602702705,"0","sequence",1], + [1602702787,"0","nocode",2], + [1602702831,"0","sequence",2], + [1602702839,"4","nocode",3], + [1602702896,"0","sequence",8], + [1602702900,"4","nocode",4], + [1602702913,"0","sequence",16] + ], + "Puzzles":{ + "indy":[12], + "nocode":[1,2,3,4,10], + "sequence":[1,2,8,16,19], + "steg":[1] + } +} +``` + ### `/register` Registers a name to a team ID. @@ -75,6 +120,29 @@ An object inspired by [JSend](https://github.com/omniti-labs/jsend): } ``` +#### Example HTTP transaction + +##### Request + +``` +POST /register HTTP/1.0 +Content-Type: application/x-www-form-urlencoded +Content-Length: 26 + +id=b387ca98&name=dirtbags +``` + +##### Repsonse + +``` +HTTP/1.0 200 OK +Content-Type: application/json +Content-Length=86 + +{"status":"success","data":{"short":"registered","description":"Team ID registered"}} +``` + + ### `/answer` Submits an answer for points. @@ -100,6 +168,29 @@ An object inspired by [JSend](https://github.com/omniti-labs/jsend): } ``` +#### Example HTTP transaction + +##### Request + +``` +POST /answer HTTP/1.0 +Content-Type: application/x-www-form-urlencoded +Content-Length: 62 + +id=b387ca98&category=sequence&points=2&answer=achilles+turnip +``` + +##### Repsonse + +``` +HTTP/1.0 200 OK +Content-Type: application/json +Content-Length=83 + +{"status":"fail","data":{"short":"not accepted","description":"Incorrect answer"}} +``` + + ### `/content/{category}/{points}/{filename}` Retrieves static content associated with a puzzle. @@ -122,3 +213,60 @@ so `curl` and `wget` can be used. Raw file octets, with a (hopefully) suitable `Content-type` HTTP header field. + +#### Example HTTP transaction + +##### Request + +``` +GET /content/sequence/1/puzzle.json HTTP/1.0 + +``` + +##### Repsonse + +``` +HTTP/1.0 200 OK +Content-Type: application/json +Content-Length: 397 + +{"Pre":{"Authors":["neale"],"Attachments":[],"Scripts":[],"Body":"\u003cp\u003e1 2 3 4 5 ⬜\u003c/p\u003e\n","AnswerPattern":"","AnswerHashes":["e7f6c011776e8db7cd330b54174fd76f7d0216b612387a5ffcfb81e6f0919683"]},"Post":{"Objective":"","Success":{"Acceptable":"","Mastery":""},"KSAs":null},"Debug":{"Log":[],"Errors":[],"Hints":[],"Summary":"Simple introduction to how this works"},"Answers":[]} +``` + + +`puzzle.json` +------- + +The special file `puzzle.json` describes a puzzle. It is a JSON object with the following fields: + +```json +{ + "Pre": { # Things which appear before the puzzle is solved + "Authors": ["Neale Pickett"], # List of puzzle authors, usually rendered as a footnote + "Attachments": ["tiger.jpg"], # List of files attached to the puzzle + "Scripts": [], # List of scripts which should be included in the HTML render of the puzzle + "Body": "

Can you find the hidden text?

\"Grr\"

\n", # HTML puzzle body + "AnswerPattern": "", # Regular expression to include in HTML input tag for validation + "AnswerHashes": [ # List of SHA265 hashes of correct answers, for client-side answer checking + "f91b1fe875cdf9e969e5bccd3e259adec5a987dcafcbc9ca8da62e341a7f29c6" + ] + }, + "Post": { # Things reveal after the puzzle is solved + "Objective": "Learn to examine images for hidden text", # Learning objective + "Success": { # Measures of learning success + "Acceptable": "Visually examine image to find hidden text", + "Mastery": "Visually examine image to find hidden text" + }, + "KSAs": null # Knowledge, Skills, and Abilities covered by this puzzle + }, + "Debug": { # Debugging output used in development: all fields are emptied when making mothballs + "Log": [], # Debug message log + "Errors": [], # Errors encountered generating this puzzzle + "Hints": [ # Hints for instructional assistants to provide to participants + "Zoom in to the image and examine all sections carefully" + ], + "Summary": "text in image" # Summary of this puzzle, to help identify it in an overview of puzzles + }, + "Answers": ["sandwich"] # List of answers: empty in production +} +``` diff --git a/pkg/transpile/mothball.go b/pkg/transpile/mothball.go index 6647d5d..ab16081 100644 --- a/pkg/transpile/mothball.go +++ b/pkg/transpile/mothball.go @@ -44,6 +44,7 @@ func Mothball(c Category, w io.Writer) error { puzzle.Debug.Errors = []string{} puzzle.Debug.Hints = []string{} puzzle.Debug.Log = []string{} + puzzle.Debug.Summary = "" // Write out Puzzle object penc := json.NewEncoder(pw)