Sudoku By MyDocz Technical Information
The Sudoku by MyDocz 'package' comprises the following primary components:
View Source : https://github.com/GrumpyGel/Sudoku_Client
SudokuServer : Server side RESTFul services for secure registration & processing of scores (best times). Built using Node.js and hosted on Windows Server using SQL Server database.
View Source : https://github.com/GrumpyGel/Sudoku_Server
Game Board Updates : New boards published from the MyDocz server in XML.
MyDocz Website : A mix of static and interactive pages, including viewing Sudoku Best Times. As an extra showcase, 2 versions of the identical website are available in both .Net and Angular platforms.
The client consists of the Sudoku.html, Sudoku.css and Sudoku.js files plus media and SudokuScores.js, SudokuBoards.js and SudokuGame.js classes.
SudokuScores class : This class is used to authenticate the client, for the client to maintain its local scores, for the server to store scores for other clients for this user and as a format to transfer data between client and server. Data contained in the created SudokuScores object is persitent on the client between sessions so that authentication and game scores are maintained.
SudokuBoards class : This class is used to maintain which boards are currently available to the client and to provide a valid randomised board when the user starts a game. Data within the created SudokuBoards object is persistent on the client between sessions so that the latest boards are availabl up to when an internet connection was last available.
SudokuGame class : This class performs the logic of game play. Taking a board from the SudokuBoards class, it holds the current status of the game board, calculates the completed board, validates user actions and determines hints if the user requests one.
Functions and Routing : The main functions within the App are its menu, game board, scores and information/settings. These functions are presented within their own popups with transitions and sound providing a configurable game experience. Routing is provides through # anchor links providing a mechanism that browser & device controls can be fully detected and replicated through code both going 'forward' and 'back'.
Client Function :The main client function delegates primary logic to the class files described above and only performs client presentation functions. Media queries present the App appropriately within a portrait or landscape layout dependant on device or browser. Animation, transition, sound are all used to provide the game experience.
Browser App : The Browser App is integrated into and launched from the MyDocz website. It has been tested on Firefox, Chrome and Safari.
Android App : The Android App is built using Apache Cordova and is available to download from the Google Play Store.
Apple iOS App : The Apple iOS App is currently being ported using Apache Cordova and is not yet available.
The SudokuServer provides data processing services to the clients and web site. Services include:
It runs on Windows Server under IIS using a SQL Server database. It is built using Node.js and unlike the client, which runs asyncronously, the services provided by the SudokuServer are procedural and use promises to run syncronously. The API is RESTful with exchange of data in JSON format and state plus authentication cached on clients. It implements various libraries:
Security & Client Authentification : Passwords are used for cryptography and database access. These are stored in a JSON file served by the IIS server under a passwords subdomain with restricted access to local IP addresses only. The Credentials object within SudokuScores identifies and authorises the client on the server. It is used as follows:
- When a client registers, the Credentials UserName property is completed and the SudokuScores structure submitted to the server with a "Register" request.
- The server creates a Users record in the database which allocates a UserID for this which is stored in the Credentials UserID property.
- The server then uses cryptography to create a 128 bit random Token representing the client device. This Token is then added to the Tokens table in the database with a reference to the UserID. The Token is then stored in the Credentials Token property.
- The concatentated UserID and Token are then Hashed using 'sha1' cryptography and a secret password. This is stored in the Credentials Hash property.
- The completed Credentials object is sent back to the client as part of the SudokuScores object and stored locally.
- Subsequent requests to the server to update scores submit this Credentials object and the same cryptography and secret password used to validate authenticated access.
Data Exchange : Core to the ability of Sudoku by MyDocz to function, is the ability for clients to register on the MyDocz server and submit score (best times) updates to it. Data is submitted from client to server in JSon format for a SudokuScores object data. This contains 3 Objects:
- Credentials : The Credentials object identifies and authorises the client on the server. Its use is as described above.
- Local : The client maintains its own scores and these are contained in the Local object. The scores are broken down into the Easy and Medium 'Levels' (of difficulty) and whether Hints were used during the game. For each of these The Number of Games, Total Time (in seconds), Fastest Time and number of games that Timed Out are stored. When the client updates the scores at the end of each game, the SudokuScores object is submitted to the server with an "Update" request. The server extracts the scores data from the Local object and stores them in the Scores table of the database.
- Server : Although not yet implemented, Sudoku by MyDocz is designed so that a User can link multiple clients to have combined scores across all their devices. This will be a mechnism where Token is created by 1 client and used by another to allocate the same UserID to both their Token records. The Server object is the combined scores for all other clients (Tokens) allocated to this User. The Server object is recalculated by the SudokuServer each time a client makes a request to it and sent back to the client for it to store.
Debugging: While the client can be debugged within a browser, the SudokuServer is developed and debugged using Visual Studio Code. The last 2 lines of code in SudokuServer.js instructs the Express framework which port to listen on. The production line can be commented and the development port 3010 line can be uncommented. The server can then be launched in Code. The client should have the "sc_UrlScoresServer" contant change to the development server:port rather than the live URL. This mismatch of domains and port creates Cross Origin Resource Sharing requests from the browser, and hence cors functionality added to SudokuServer.
Game Board Updates
Sudoku by MyDocz uses predefined games bords. When a game starts, a board is chosen at random and its layout randomised. This creates many permutations of boards, but it is a limited number.
Therefore, the client has a mechanism of downloading new boards as published on the MyDocz website. The new boards are simply a "SudokuBoards.xml" file placed on the server. Contained in it is an expiry date informing the client when to next check for updates.
JSON would have been the appropriate format to hold these updates. However, XML was chosen simply to showcase another technology within Sudoku by MyDocz. Downloading of the XML content is handled in the client Sudoku.js using an XMLHttpRequest and the DOM data extraction handled by the SudokuBoards class.
Although a relatively simple website, it has a consistent layout through all pages and is fully responsive to the hosting device.
The website has been created in .Net, c# and XSLT page transforms.
A complete duplicated website is also showcased Angular at http://www.mydocz.com/Angular.