diff --git a/Database.md b/Database.md index be376f2..1f7444f 100644 --- a/Database.md +++ b/Database.md @@ -1,39 +1,65 @@ # Database -Used database schema is generated by ORM framework Doctrine from ReCodEx API source code. Tables are directly mapped to _entities_, which are PHP classes annotated with data provided by ORM framework. In the following text there is a brief description of each such entity. There may be some additional database tables for many-to-many relations between entities, but these tables are not discussed in detail because there are only two columns with keys of both related tables in each one. Graphical database schema is added as attachement to this documentation. +Used database schema is generated by ORM framework Doctrine from ReCodEx API +source code. Tables are directly mapped to _entities_, which are PHP classes +annotated with data provided by ORM framework. In the following text there is a +brief description of each such entity. There may be some additional database +tables for many-to-many relations between entities, but these tables are not +discussed in detail because there are only two columns with keys of both +related tables in each one. Graphical database schema is added as attachement +to this documentation. ## Assignment -Assignment table represents exercise assignment in a group. It holds keys of the exercise (_exerciseId_) and group (_groupId_) where is the exercise assigned. Other columns are: - -- _isPublic_ -- assignment can be public (visible to students) or private (visible only to supervisor of the group) -- _submissionCountLimit_ -- number of attempts student can make to solve the exercise -- _scoreConfig_ -- configuration for calculating point score; actual syntax depends on used score calculator +Assignment table represents exercise assignment in a group. It holds keys of +the exercise (_exerciseId_) and group (_groupId_) where is the exercise +assigned. Other columns are: + +- _name_ -- visible assignment identifier +- _isPublic_ -- assignment can be public (visible to students) or private + (visible only to supervisor of the group) +- _submissionCountLimit_ -- number of attempts student can make to solve the + exercise +- _scoreConfig_ -- configuration for calculating point score; actual syntax + depends on used score calculator - _firstDeadline_ -- date and time after that no new submissions are received -- _allowSecondDeadline_, _secondDeadline_ -- flag if another deadline is allowed, date and time of that deadline -- _maxPointsBeforeFirstDeadline_, _maxPointsBeforeSecondDedline_ -- maximal amount of points for correct solutions for first (respectively second) deadline -- _scoreCalculator_ -- name of used score score calculator or NULL for API's default one -- _canViewLimitRatios_ -- flag if student can view percentage of used time and memory limits for each test -- _deletedAt_ -- assignment cannot be deleted due to possible numerous dependencies, but can be hidden from the users; published assignments have NULL value, deleted ones have time of deletion +- _allowSecondDeadline_, _secondDeadline_ -- flag if another deadline is + allowed, date and time of that deadline +- _maxPointsBeforeFirstDeadline_, _maxPointsBeforeSecondDeadline_ -- maximal + amount of points for correct solutions for first (respectively second) + deadline +- _scoreCalculator_ -- name of used score score calculator or NULL for API's + default one +- _canViewLimitRatios_ -- flag if student can view percentage of used time and + memory limits for each test +- _deletedAt_ -- assignment cannot be deleted due to possible numerous + dependencies, but can be hidden from the users; published assignments have + NULL value, deleted ones have time of deletion +- _version_ -- @todo +- _isBonus_ -- @todo +- _pointsPercentualThreshold_ -- @todo ## Comment -Comment entity holds one message published in a comment thread (standalone +Comment entity holds one message published in a comment thread (standalone comments are not permitted). -- _commentThread_, _user_ -- keys of thread where this comment belongs and author of the comment +- _commentThread_, _user_ -- keys of thread where this comment belongs and + author of the comment - _isPrivate_ -- flag if the comment is for author only or public - _postedAt_ -- date and time of comment post - _text_ -- content of the comment ## CommentThread -CommentThread entity contains all comments in one thread by one-to-many relation. From database perspective, this table has only one column with primary key and the relation is made by foreign key column in Comment table. +CommentThread entity contains all comments in one thread by one-to-many +relation. From database perspective, this table has only one column with +primary key and the relation is made by foreign key column in Comment table. ## Exercise -Exercise is a structure that describes a programming problem. Exercises can have -a tree structure (_exerciseId_ of parent) that can be used to implement an +Exercise is a structure that describes a programming problem. Exercises can +have a tree structure (_exerciseId_ of parent) that can be used to implement an inheritance mechanism, but it's currently not being used. - _author_ -- key for user entity of the author @@ -41,12 +67,16 @@ inheritance mechanism, but it's currently not being used. - _version_ -- version of the exercise; each edit increases this counter - _createdAt_ -- date and time of creation - _updatedAt_ -- date and time of last modification -- _difficulty_ -- description of difficulty, curretly used ones are easy, medium and hard -- _isPublic_ -- flag if the exercise is publicly visible to all supervisors or only to author +- _difficulty_ -- description of difficulty, curretly used ones are easy, + medium and hard +- _isPublic_ -- flag if the exercise is publicly visible to all supervisors or + only to author +- _description_ -- @todo ## ExerciseFile -ExerciseFile entity is extension of UploadedFile entity, so they share one database table. Exercise file has some additional data: +ExerciseFile entity is extension of UploadedFile entity, so they share one +database table. Exercise file has some additional data: - _hashName_ -- `sha1sum` of file content, used as name in job configurations - _fileServerPath_ -- URL where the file is stored on file server @@ -54,7 +84,8 @@ ExerciseFile entity is extension of UploadedFile entity, so they share one datab ## ExternalLogin -ExternalLogin entity provides mapping between username in external login service and local user account. +ExternalLogin entity provides mapping between username in external login +service and local user account. - _user_ -- key to local user entity - _authService_ -- identifier which extrnal service is the user using @@ -64,45 +95,63 @@ ExternalLogin entity provides mapping between username in external login service This entity is used for logging requests about password resets. -- _user_ -- key to user who requested the password change (or NULL if not known) +- _user_ -- key to user who requested the password change (or NULL if not + known) - _requestedAt_ -- date and time of password reset request - _sentTo_ -- email address where the reset token was sent to - _redirectUrl_ -- URL where the user is supposed to change his password -- _IPaddress_ -- IP address from where the request came from (parsed from HTTP request header) +- _IPaddress_ -- IP address from where the request came from (parsed from HTTP + request header) ## Group -Group entity contains data about a group. They can be hierarchical, reference to the parent is obtained by _parentGroup_ key. Top level groups has this field set to NULL. Each group belongs to one instance referenced by _instance_ key. Also, each group has its administrator user referenced by _admin_ key. Other data: +Group entity contains data about a group. They can be hierarchical, reference +to the parent is obtained by _parentGroup_ key. Top level groups has this field +set to NULL. Each group belongs to one instance referenced by _instance_ key. +Also, each group has its administrator user referenced by _admin_ key. Other +data: - _name_ -- name of the group - _description_ -- Markdown styled text description of the group -- _threshold_ -- percentage of maximal points required to complete the course in float between 0 and 1 (or NULL) -- _publicStats_ -- flag if user can view total number of points for other users in the group -- _isPublic_ -- flag if the group is visible for all students in instance or it is hidden (only for members) -- _externalId_ -- external identifier of the group (or NULL), for example course code like NPRG042 +- _threshold_ -- percentage of maximal points required to complete the course + in float between 0 and 1 (or NULL) +- _publicStats_ -- flag if user can view total number of points for other users + in the group +- _isPublic_ -- flag if the group is visible for all students in instance or it + is hidden (only for members) +- _externalId_ -- external identifier of the group (or NULL), for example + course code like NPRG042 +- _deletedAt_ -- @todo ## GroupMembership -GroupMembership represents relation between group and its members. Also it contains additional data, so this entity is not autogenerated by Doctrine. Essential parts are keys to user and group entities (_user_ and _group_ keys). Additional data: +GroupMembership represents relation between group and its members. Also it +contains additional data, so this entity is not autogenerated by Doctrine. +Essential parts are keys to user and group entities (_user_ and _group_ keys). +Additional data: -- _status_ -- user status in the group, one of _requested_, _accepted_ and _rejected_ +- _status_ -- user status in the group, one of _requested_, _accepted_ and + _rejected_ - _type_ -- type of user access, one of _student_, _supervisor_ and * for all - _requestedAt_ -- date and time the join request was received (or NULL) - _joindedAt_ -- date and time the request for joining was accepted (or NULL) - _rejectedAt_ -- date and time the request for joining was rejected (or NULL) -- _studentSince_ -- date and time when the user became a student, usually time of registration (or NULL) -- _supervisorSince_ -- date and time when the user became a supervisor (or NULL) +- _studentSince_ -- date and time when the user became a student, usually time + of registration (or NULL) +- _supervisorSince_ -- date and time when the user became a supervisor (or + NULL) ## HardwareGroup -HardwareGroup entity represents used hardware groups by the backend. Currently -this table has to be changed manually when a new hardware group is added, but it -is possible to automate this in the future. The hardware group has only one +HardwareGroup entity represents used hardware groups by the backend. Currently +this table has to be changed manually when a new hardware group is added, but +it is possible to automate this in the future. The hardware group has only one column with data, the textual _description_. ## HardwareGroupAvailabilityLog -This entity provides information about hardware group changes during time. System administrator should keep the data up-to-date with backend state. +This entity provides information about hardware group changes during time. +System administrator should keep the data up-to-date with backend state. - _hardwareGroup_ -- key to HardwareGroup entity - _isAvailable_ -- flag if the hardware group becomes available or disabled @@ -111,20 +160,26 @@ This entity provides information about hardware group changes during time. Syste ## Instance -Instance entity represents separation of multiple organisations using the same API server. Each group or user belong to exactly one instance. User permissions are only valid in his instance. +Instance entity represents separation of multiple organisations using the same +API server. Each group or user belong to exactly one instance. User permissions +are only valid in his instance. - _admin_ -- key referencing administrator user entity +- _name_ -- @todo - _description_ -- Markdown styled textual description - _isOpen_ -- flag if new user can register themselves in this instance - _isAllowed_ -- flag if the instance cen be used or is disabled for all users - _createdAt_ -- date and time of instance creation - _updatedAt_ -- date and time of last modification - _needsLicence_ -- flag if this instance needs a velid license -- _deletedAt_ -- instance cannot be directly deleted due to possibility of many dependencies, but instead it can be hidden from users by setting this field to date and time of deletion (active instances have NULL value) +- _deletedAt_ -- instance cannot be directly deleted due to possibility of many + dependencies, but instead it can be hidden from users by setting this field + to date and time of deletion (active instances have NULL value) ## Licence -Licence entity gives validity to instance. For normal usage an instance needs valid licence for proper functionality. +Licence entity gives validity to instance. For normal usage an instance needs +valid licence for proper functionality. - _instance_ -- instance key the licence is bound to - _isValid_ -- flag if this licence is valid or blocked by administrator @@ -133,78 +188,115 @@ Licence entity gives validity to instance. For normal usage an instance needs va ## LocalizedText -LocalizedText entity represent text or description of the problem in one language mutation. Exercises and assignments uses these text to display problem description to users. The text can be Markdown styled. +LocalizedText entity represent text or description of the problem in one +language mutation. Exercises and assignments uses these text to display problem +description to users. The text can be Markdown styled. -- _name_ -- title of this localized text -- _locale_ -- language code of locale this text is written in (for example _en_) -- _description_ -- text content -- _localizedText_ -- key refering to parent localized text; when editing, new version is created as a child of the original one +- _locale_ -- language code of locale this text is written in (for example + _en_) +- _text_ -- text content +- _createdFrom_ -- key refering to parent localized text; when editing, new + version is created as a child of the original one - _createdAt_ -- date and time of creation ## Login -Login entity holds credentials for logging into ReCodEx system using internal authentication. +Login entity holds credentials for logging into ReCodEx system using internal +authentication. - _user_ -- key refering to user entity - _username_ -- mail of the user -- _passwordHash_ -- hashed password, generated by Nette [Passwords::hash()](https://api.nette.org/2.3/source-Security.Passwords.php.html#27) method +- _passwordHash_ -- hashed password, generated by Nette + [Passwords::hash()](https://api.nette.org/2.3/source-Security.Passwords.php.html#27) + method ## Permission -Permission entity holds permissions for user roles. API endpoints can have a permission restriction assigned by annotation _@UserIsAllowed(exercises="view-all")_ which are checked before endpoint invocation. These permission are gained to user roles in this entity. +Permission entity holds permissions for user roles. API endpoints can have a +permission restriction assigned by annotation +_@UserIsAllowed(exercises="view-all")_ which are checked before endpoint +invocation. These permission are gained to user roles in this entity. - _role_ -- key of the role this permission is assigned to -- _resource_ -- resource name, usually same for all endpoints in one presenter; from the example above resource is _exercises_ string -- _action_ -- action, usually different for each endpoint, wildcard can be +- _resource_ -- resource name, usually same for all endpoints in one presenter; + from the example above resource is _exercises_ string +- _action_ -- action, usually different for each endpoint, wildcard can be specified as *; in the example above, _view-all_ is the action - _isAllowed_ -- flag if the rule is allowed of denied ## ReferenceExerciseSolution -ReferenceExerciseSolution contains additional data for reference solution than normal solution created by student submit. +ReferenceExerciseSolution contains additional data for reference solution than +normal solution created by student submit. -- _exercise_, _solution_ -- keys refering to exercise this entity is bound to and solution entity used for submitting +- _exercise_, _solution_ -- keys refering to exercise this entity is bound to + and solution entity used for submitting - _uploadedAt_ -- date and time of creation -- _description_ -- textual description of used algorithm or other note about the particular solution +- _description_ -- textual description of used algorithm or other note about + the particular solution ## ReferenceSolutionEvaluation -ReferenceSolutionEvaluation contains additional data for reference solution evalution than normal evaluation created on student solution evaluation. +ReferenceSolutionEvaluation contains additional data for reference solution +evalution than normal evaluation created on student solution evaluation. - _referenceSolution_ -- key to solution which this evaluation belongs to - _hwGroup_ -- hardware group which was used during execution on worker -- _resultsUrl_ -- filserver address from where results of reference evaluation can be internally accessed +- _resultsUrl_ -- filserver address from where results of reference evaluation + can be internally accessed - _evaluation_ -- associated general evaluation key ## ReportedErrors -All errors which were reported to API from backend are sent as emails to administrator of system and also stored in this entity. +All errors which were reported to API from backend are sent as emails to +administrator of system and also stored in this entity. - _type_ -- textual description of error type -- _recipients_ -- list of comma separated email addresses to which error was sent +- _recipients_ -- list of comma separated email addresses to which error was + sent - _subject_ -- subject as it was sent in email - _sentAt_ -- date and time when email with error report was sent - _description_ -- message as it was sent in email ## Resource -Resource entity represent different resources used in ReCodEx system. These resources can be used in presenter actions for access restrictions. Resource contain list of permissions in one-to-many relation, but from database perspective this table has only one column with the resource name. +Resource entity represent different resources used in ReCodEx system. These +resources can be used in presenter actions for access restrictions. Resource +contain list of permissions in one-to-many relation, but from database +perspective this table has only one column with the resource name. ## Role -Each ReCodEx user has exactly one role. A role is associated with multiple -permissions that determine what actions can a user with that role perform on a +Each ReCodEx user has exactly one role. A role is associated with multiple +permissions that determine what actions can a user with that role perform on a resource. - _id_ -- textual identification of the role - _parentRole_ -- reference to parent role -- _childRoles_ -- array of roles which have this one as parent; not actual +- _childRoles_ -- array of roles which have this one as parent; not actual database column, relation stored using _parentRole_ column -- _permissions_ -- permissions which are connected to this role; not actual database column, many-to-one relation stored in Permission entity +- _permissions_ -- permissions which are connected to this role; not actual + database column, many-to-one relation stored in Permission entity + +## RuntimeConfig + +RuntimeConfig entity connects job configuration to runtime environment. This +entity is backed up on every update, old version is set as _createdFrom_ key in +the new version. On student submission one runtime config is chosen based on +files extensions and corresponding job configuration is used for evaluation in +the backend. + +- _name_ -- human readable identificator of runtime configuration +- _runtimeEnvironment_ -- corresponding runtime environment +- _jobConfigFilePath_ -- path to job configuration which is stored at API + server +- _createdAt_ -- date and time of entity creation ## RuntimeEnvironment -Stores information about supported environments which can be used for evaluation on workers. On student submit the correct environment is determined by extensions of uploaded files. +Stores information about supported environments which can be used for +evaluation on workers. On student submit the correct environment is determined +by extensions of uploaded files. - _name_ -- human readable name of runtime environment - _language_ -- language which can be used in this environment @@ -214,71 +306,85 @@ Stores information about supported environments which can be used for evaluation ## Solution -Solution is a general entity which is used for all types of evaluations, -including students and reference solutions. This entity can be shared between -multiple submissions (for example resubmit by supervisor in case of backend +Solution is a general entity which is used for all types of evaluations, +including students and reference solutions. This entity can be shared between +multiple submissions (for example resubmit by supervisor in case of backend failure). - _user_ -- user key to whom this solution belongs to -- _files_ -- exercise solution files which user uploaded and are associated with solution; not actual database column, one-to-many relation is stored by each file -- _runtimeConfig_ -- runtime configuration key which was used during execution on worker +- _files_ -- exercise solution files which user uploaded and are associated + with solution; not actual database column, one-to-many relation is stored by + each file +- _runtimeConfig_ -- runtime configuration key which was used during execution + on worker - _evaluated_ -- true if solution was evaluated and results were processed ## SolutionEvaluation -SolutionEvaluation entity represents evaluation of student or reference solution. It contains parsed and processed data received from backend. +SolutionEvaluation entity represents evaluation of student or reference +solution. It contains parsed and processed data received from backend. - _evaluatedAt_ -- date and time of evaluation creation -- _initFailed_ -- if true then one of the initiation tasks failed thus solution cannot be even compiled -- _score_ -- overall score of user solution (percentual correctness from 0 to 1) +- _initFailed_ -- if true then one of the initiation tasks failed thus solution + cannot be even compiled +- _score_ -- overall score of user solution (percentual correctness from 0 to + 1) - _points_ -- points which were assigned to user for this solution - _bonusPoints_ -- bonus points assigned by one of the supervisors -- _isValid_ -- can be used to ban user solution of exercise due to various reasons +- _isValid_ -- can be used to ban user solution of exercise due to various + reasons - _evaluationFailed_ -- true if whole evaluation failed on worker - _resultYml_ -- whole yaml file with evaluation results acquired from backend -- _testResults_ -- results of all tests associated with user solution; not actual database table, one-to-many relation is stored by TestResult entities +- _testResults_ -- results of all tests associated with user solution; not + actual database table, one-to-many relation is stored by TestResult entities ## SolutionFile -SolutionFile entity is extension of UploadedFile entity, so they share one database table. Solution file has one additional column of associated solution key. - -## RuntimeConfig - -runtimeConfig entity connects job configuration to runtime environment. This entity is backed up on every update, old version is set as _createdFrom_ key in the new version. On student submission one runtime config is chosen based on files extensions and corresponding job configuration is used for evaluation in the backend. - -- _name_ -- human readable identificator of runtime configuration -- _runtimeEnvironment_ -- corresponding runtime environment -- _jobConfigFilePath_ -- path to job configuration which is stored at API server -- _createdAt_ -- date and time of entity creation +SolutionFile entity is extension of UploadedFile entity, so they share one +database table. Solution file has one additional column of associated solution +key. ## Submission -Submission entity corresponds to student submit of assignment. It stores both information about submission and about subsequent evaluation. +Submission entity corresponds to student submit of assignment. It stores both +information about submission and about subsequent evaluation. - _submittedAt_ -- date and time of submission creation - _note_ -- user can provide note to exercise solution -- _resultsUrl_ -- URL pointed to fileserver from which results of submission can be internally downloaded +- _resultsUrl_ -- URL pointed to fileserver from which results of submission + can be internally downloaded - _assignment_ -- corresponding assignment key to which submission belongs to - _user_ -- key of user to whom submission belongs to -- _submittedBy_ -- user who submitted solution of exercise, can be supervisor for instance +- _submittedBy_ -- user who submitted solution of exercise, can be supervisor + for instance - _solution_ -- corresponding solution -- _asynchronous_ -- exercise solution was submitted asynchronously, this happens when supervisor or superadmin submit solution for particular user +- _asynchronous_ -- exercise solution was submitted asynchronously, this + happens when supervisor or superadmin submit solution for particular user - _evaluation_ -- evaluation of this submission ## SubmissionFailure -A queue of failed submissions which need further attention from the -administrator. Administrator can then resolve this issue and information about +A queue of failed submissions which need further attention from the +administrator. Administrator can then resolve this issue and information about that will be stored too. -- _type_ -- type of failure, can be for example _broker_reject_ or _evaluation_failure_ +- _type_ -- type of failure, can be for example _broker_reject_ or + _evaluation_failure_ - _description_ -- description of failure which was provided by backend - _submission_ -- associated submission which failed - _createdAt_ -- date and time of entity creation - _resolvedAt_ -- date and time when failure was resolved - _resolutionNote_ -- user can provide description when failure is resolved +## TaskResult + +@todo + +- _taskName_ -- @todo +- _usedTime_ -- @todo +- _usedMemory_ -- @todo + ## TestResult TestResult entity represents result of one logical test from job configuration. @@ -288,17 +394,22 @@ TestResult entity represents result of one logical test from job configuration. - _solutionEvaluation_ -- evaluation to which test result belongs - _score_ -- score which was assigned to test evaluation by judge - _memoryExceeded_ -- true if memory limit was exceeded -- _usedMemoryRatio_ -- float number from 0 to 1 which represents percentage of user solution memory usage against memory limit from configuration +- _usedMemoryRatio_ -- float number from 0 to 1 which represents percentage of + user solution memory usage against memory limit from configuration - _timeExceeded_ -- true if time limit was exceeded -- _usedTimeRatio_ -- float number from 0 to 1 which represents percentage of user solution time usage against time limit from configuration +- _usedTimeRatio_ -- float number from 0 to 1 which represents percentage of + user solution time usage against time limit from configuration - _exitCode_ -- exit code which whole test returns - _message_ -- provided only on non-zero exit code -- _stats_ -- textual representation of whole information about evaluation of test which arrived from worker +- _stats_ -- textual representation of whole information about evaluation of + test which arrived from worker - _judgeOutput_ -- output textual message from judge ## UploadedFile -Entity which represents one file which was uploaded to API server. This entity uses _Single Table Inheritance_ and its children are ExerciseFile and SolutionFile entities. +Entity which represents one file which was uploaded to API server. This entity +uses _Single Table Inheritance_ and its children are ExerciseFile and +SolutionFile entities. - _name_ -- original name of file uploaded to API - _localFilePath_ -- destination where file is stored on API server @@ -317,7 +428,8 @@ Keeps information about all users registered in ReCodEx. - _email_ -- email address which is used for sending email notifications - _avatarUrl_ -- url of profile picture - _isVerified_ -- user verified his email address (not used at the moment) -- _isAllowed_ -- if this field is set to false user cannot sign in to application +- _isAllowed_ -- if this field is set to false user cannot sign in to + application - _createdAt_ -- date and time of user registration - _instance_ -- instance to which user belongs to - _settings_ -- settings which are connected to this user @@ -327,7 +439,7 @@ Keeps information about all users registered in ReCodEx. ## UserAction -Stores information about what routes on API user visited and some additional +Stores information about what routes on API user visited and some additional information about it. This data is collected only from logged users. - _user_ -- which user performed API request @@ -335,13 +447,16 @@ information about it. This data is collected only from logged users. - _action_ -- action which was requested on API - _params_ -- GET or POST parameters given by user - _code_ -- return code which was sent back by API -- _data_ -- if call ended up with an exception, description of thrown exception should be there +- _data_ -- if call ended up with an exception, description of thrown exception + should be there ## UserSettings -User settings belong to some user and contains settings mostly for web application. +User settings belong to some user and contains settings mostly for web +application. - _darkTheme_ -- dark mode will be used in text editor in web application -- _vimMode_ -- turn vim mode keybinding on in text editor used by web application +- _vimMode_ -- turn vim mode keybinding on in text editor used by web + application - _defaultLanguage_ -- default language which will be used in web application - +- _openedSidebar_ -- @todo