Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Communication system for embedded WW problems #16

Open
wants to merge 14 commits into
base: develop
Choose a base branch
from
Open

Communication system for embedded WW problems #16

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
14 commits
Select commit Hold shift + click to select a range
6358737
Static file support if baseURL is nonempty
drdrew42 May 19, 2023
accb165
Convert static URLs from relative to absolute
drdrew42 May 19, 2023
3799b11
Convert all problem requests to JWT
drdrew42 May 19, 2023
381c1ff
do not require provided sourcecode to be in base64
drdrew42 May 22, 2023
3ac56a0
refactor and cleanup
drdrew42 May 22, 2023
11ef91a
convert to WW2.18 mojo::template approach
drdrew42 Jun 6, 2023
a9f746d
reorganization and file cleanup
drdrew42 Jun 10, 2023
246eb21
fix preview logic
drdrew42 Jun 12, 2023
7165c98
remove PGaddons
drdrew42 Jun 12, 2023
4372a28
call this function!
drdrew42 Jun 12, 2023
f1ad558
Dockerfile and documentation update
drdrew42 Jun 14, 2023
acf1828
proper handling of hideButton options
drdrew42 Jun 20, 2023
77bbf19
properly serve entire app with extended base URL
drdrew42 Jun 20, 2023
b5b1767
rendered problem emits interaction data
drdrew42 Jun 22, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 5 additions & 1 deletion .gitignore
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,8 +9,12 @@ private/
tmp/*
!tmp/.gitkeep
logs/*.log

node_modules
node_modules/*
public/**/*.min.js
public/**/*.min.css
public/static-assets.json

*.o
*.pm.tdy
*.bs
Expand Down
2 changes: 1 addition & 1 deletion Dockerfile
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -55,7 +55,7 @@ RUN cp render_app.conf.dist render_app.conf

RUN cp conf/pg_config.yml lib/PG/conf/pg_config.yml

RUN npm install
RUN cd public/ && npm install && cd ..

RUN cd lib/PG/htdocs && npm install && cd ../../..

Expand Down
166 changes: 112 additions & 54 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -51,7 +51,9 @@ If using a local install instead of docker:
* copy `render_app.conf.dist` to `render_app.conf` and make any desired modifications
* copy `conf/pg_config.yml` to `lib/PG/pg_config.yml` and make any desired modifications
* install third party JavaScript dependencies
* `cd private/`
* `npm install`
* `cd ..`
* install PG JavaScript dependencies
* `cd lib/PG/htdocs`
* `npm install`
Expand All @@ -70,59 +72,115 @@ If using a local install instead of docker:

![image](https://user-images.githubusercontent.com/3385756/129100124-72270558-376d-4265-afe2-73b5c9a829af.png)

## Server Configuration

Modification of `baseURL` may be necessary to separate multiple services running on `SITE_HOST`, and will be used to extend `SITE_HOST`. The result of this extension will serve as the root URL for accessing the renderer (and any supplementary assets it may need to provide in support of a rendered problem). If `baseURL` is an absolute URL, it will be used verbatim -- userful if the renderer is running behind a load balancer.

By default, `formURL` will further extend `baseURL`, and serve as the form-data target for user interactions with problems rendered by this service. If `formURL` is an absolute URL, it will be used verbatim -- useful if your implementation intends to sit in between the user and the renderer.

## Renderer API

Can be interfaced through `/render-api`

## Parameters

| Key | Type | Default Value | Required | Description | Notes |
| --- | ---- | ------------- | -------- | ----------- | ----- |
| problemSourceURL | string | null | true if `sourceFilePath` and `problemSource` are null | The URL from which to fetch the problem source code | Takes precedence over `problemSource` and `sourceFilePath`. A request to this URL is expected to return valid pg source code in base64 encoding. |
| problemSource | string (base64 encoded) | null | true if `problemSourceURL` and `sourceFilePath` are null | The source code of a problem to be rendered | Takes precedence over `sourceFilePath`. |
| sourceFilePath | string | null | true if `problemSource` and `problemSourceURL` are null | The path to the file that contains the problem source code | Can begin with Library/ or Contrib/, in which case the renderer will automatically adjust the path relative to the webwork-open-problem-library root. Path may also begin with `private/` for local, non-OPL content. |
| problemSeed | number | NA | true | The seed to determine the randomization of a problem | |
| psvn | number | 123 | false | used for consistent randomization between problems | |
| formURL | string | /render-api | false | the URL for form submission | |
| baseURL | string | / | false | the URL for relative paths | |
| format | string | '' | false | Determine how the response is formatted ('html' or 'json') ||
| outputFormat | string (enum) | static | false | Determines how the problem should render, see below descriptions below | |
| language | string | en | false | Language to render the problem in (if supported) | |
| showHints | number (boolean) | 1 | false | Whether or not to show hints | |
| showSolutions | number (boolean) | 0 | false | Whether or not to show the solutions | |
| permissionLevel | number | 0 | false | Deprecated. See below. |
| isInstructor | number (boolean) | 0 | false | Is the user viewing the problem an instructor or not. | Used by PG to determine if scaffolds can be allowed to be open among other things |
| problemNumber | number | 1 | false | We don't use this | |
| numCorrect | number | 0 | false | The number of correct attempts on a problem | |
| numIncorrect | number | 1000 | false | The number of incorrect attempts on this problem | |
| processAnswers | number (boolean) | 1 | false | Determines whether or not answer json is populated, and whether or not problem_result and problem_state are non-empty | |
| answersSubmitted | number (boolean) | ? | false? | Determines whether to process form-data associated to the available input fields | |
| showSummary | number (boolean) | ? | false? | Determines whether or not to show the summary result of processing the form-data associated with `answersSubmitted` above ||
| showComments | number (boolean) | 0 | false | Renders author comment field at the end of the problem ||
| includeTags | number (boolean) | 0 | false | Includes problem tags in the returned JSON | Only relevant when requesting `format: 'json'` |

## Output Format

| Key | Description |
| ----- | ----- |
| static | zero buttons, locked form fields (read-only) |
| nosubmit | zero buttons, editable (for exams, save problem state and submit all together) |
| single | one submit button (intended for graded content) |
| classic | preview + submit buttons |
| simple | preview + submit + show answers buttons |
| practice | check answers + show answers buttons |

## Permission level

| Key | Value |
| --- | ----- |
| student | 0 |
| prof | 10 |
| admin | 20 |

## Permission logic summary

* `permissionLevel` is ignored if `isInstructor` is directly set.
* If `permissionLevel >= 10`, then `isInstructor` will be set to true.
* If `permissionLevel < 10`, then `isInstructor` will be set to false.
* `permissionLevel` is not used to determine if hints or solutions are shown.
Can be accessed by POST to `{SITE_HOST}{baseURL}{formURL}`.

By default, `localhost:3000/render-api`.

### **REQUIRED PARAMETERS**

The bare minimum of parameters that must be included are:
* the code for the problem, so, **ONE** of the following (in order of precedence):
* `problemSource` (raw pg source code, _can_ be base64 encoded)
* `sourceFilePath` (relative to OPL `Library/`, `Contrib/`; or in `private/`)
* `problemSourceURL` (fetch the pg source from remote server)
* a "seed" value for consistent randomization
* `problemSeed` (integer)

| Key | Type | Description | Notes |
| --- | ---- | ----------- | ----- |
| problemSource | string (possibly base64 encoded) | The source code of a problem to be rendered | Takes precedence over `sourceFilePath`. |
| sourceFilePath | string | The path to the file that contains the problem source code | Renderer will automatically adjust `Library/` and `Contrib/` relative to the webwork-open-problem-library root. Path may also begin with `private/` for local, non-OPL content. |
| problemSourceURL | string | The URL from which to fetch the problem source code | Takes precedence over `problemSource` and `sourceFilePath`. A request to this URL is expected to return valid pg source code in base64 encoding. |
| problemSeed | number | The seed that determines the randomization of a problem | |

**ALL** other request parameters are optional.

### Infrastructure Parameters

The defaults for these parameters are set in `render_app.conf`, but these can be overridden on a per-request basis.

| Key | Type | Default Value | Description | Notes |
| --- | ---- | ------------- | ----------- | ----- |
| baseURL | string | '/' (as set in `render_app.conf`) | the URL for relative paths | |
| formURL | string | '/render-api' (as set in `render_app.conf`) | the URL for form submission | |

### Display Parameters

#### Formatting

Parameters that control the structure and templating of the response.

| Key | Type | Default Value | Description | Notes |
| --- | ---- | ------------- | ----------- | ----- |
| language | string | en | Language to render the problem in (if supported) | affects the translation of template strings, _not_ actual problem content |
| _format | string | 'html' | Determine how the response is _structured_ ('html' or 'json') | usually 'html' if the user is directly interacting with the renderer, 'json' if your CMS sits between user and renderer |
| outputFormat | string | 'default' | Determines how the problem should be formatted | 'default', 'static', 'PTX', 'raw', or |
| displayMode | string | 'MathJax' | How to prepare math content for display | 'MathJax' or 'ptx' |

#### User Interactions

Control how the user is allowed to interact with the rendered problem.

Requesting `outputFormat: 'static'` will prevent any buttons from being included in the rendered output, regardless of the following options.

| Key | Type | Default Value | Description | Notes |
| --- | ---- | ------------- | ----------- | ----- |
| hidePreviewButton | number (boolean) | false | "Preview My Answers" is enabled by default | |
| hideCheckAnswersButton | number (boolean) | false | "Submit Answers" is enabled by default | |
| showCorrectAnswersButton | number (boolean) | `isInstructor` | "Show Correct Answers" is disabled by default, enabled if `isInstructor` is true (see below) | |

#### Content

Control what is shown to the user: hints, solutions, attempt results, scores, etc.

| Key | Type | Default Value | Description | Notes |
| --- | ---- | ------------- | ----------- | ----- |
| permissionLevel | number | 0 | **DEPRECATED.** Use `isInstructor` instead. |
| isInstructor | number (boolean) | 0 | Is the user viewing the problem an instructor or not. | Used by PG to determine if scaffolds can be allowed to be open among other things |
| showHints | number (boolean) | 1 | Whether or not to show hints | |
| showSolutions | number (boolean) | `isInstructor` | Whether or not to show the solutions | |
| hideAttemptsTable | number (boolean) | 0 | Hide the table of answer previews/results/messages | If you have a replacement for flagging the submitted entries as correct/incorrect |
| showSummary | number (boolean) | 1 | Determines whether or not to show a summary of the attempt underneath the table | Only relevant if the Attempts Table is shown `hideAttemptsTable: false` (default) |
| showComments | number (boolean) | 0 | Renders author comment field at the end of the problem | |
| showFooter | number (boolean) | 0 | Show version information and WeBWorK copyright footer | |
| includeTags | number (boolean) | 0 | Includes problem tags in the returned JSON | Only relevant when requesting `_format: 'json'` |

## Using JWTs

There are three JWT structures that the Renderer uses, each containing its predecessor:
* problemJWT
* sessionJWT
* answerJWT

### ProblemJWT

This JWT encapsulates the request parameters described above, under the API heading. Any value set in the JWT cannot be overridden by form-data. For example, if the problemJWT includes `isInstructor: 0`, then any subsequent interaction with the problem rendered by this JWT cannot override this setting by including `isInstructor: 1` in the form-data.

### SessionJWT

This JWT encapsulates a user's attempt on a problem, including:
* the text and LaTeX versions of each answer entry
* count of incorrect attempts (stopping after a correct attempt, or after `showCorrectAnswers` is used)
* the problemJWT

If stored (see next), this JWT can be submitted as the sole request parameter, and the response will effectively restore the users current state of interaction with the problem (as of their last submission).

### AnswerJWT

If the initial problemJWT contains a value for `JWTanswerURL`, this JWT will be generated and sent to the specified URL. The answerJWT is the only content provided to the URL. The renderer is intended to to be user-agnostic. It is recommended that the JWTanswerURL specify the unique identifier for the user/problem combination. (e.g. `JWTanswerURL: 'https://db.yoursite.org/grades-api/:user_problem_id'`)

For security purposes, this parameter is only accepted when included as part of a JWT.

This JWT encapsulates the status of the user's interaction with the problem.
* score
* sessionJWT

The goal here is to update the `JWTanswerURL` with the score and "state" for the user. If you have uses for additional information, please feel free to suggest as a GitHub Issue.
4 changes: 1 addition & 3 deletions conf/pg_config.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -40,6 +40,7 @@ directories:
# (in this order) by loadMacros when it looks for a .pl macro file.
macrosPath:
- .
- $render_root/private/macros
- $pg_root/macros
- $pg_root/macros/answers
- $pg_root/macros/capa
Expand Down Expand Up @@ -182,9 +183,6 @@ options:
# This is the operations file to use for mathview, each contains a different locale.
mathViewLocale: mv_locale_us.js

# Set to 1 to show the WirisEditor preview system.
useWirisEditor: 0

# Catch translation warnings internally.
catchWarnings: 1

Expand Down
64 changes: 36 additions & 28 deletions lib/RenderApp.pm
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,31 +3,32 @@ use Mojo::Base 'Mojolicious';

BEGIN {
use Mojo::File;
$main::dirname = Mojo::File::curfile->dirname;
$main::libname = Mojo::File::curfile->dirname;

# RENDER_ROOT is required for initializing conf files.
$ENV{RENDER_ROOT} = $main::dirname->dirname
$ENV{RENDER_ROOT} = $main::libname->dirname
unless ( defined( $ENV{RENDER_ROOT} ) );

# PG_ROOT is required for PG/lib/PGEnvironment.pm, FormatRenderedProblem.pm, and RenderProblem.pm.
# This is hardcoded to avoid conflict with the environment variable for webwork2.
# There is no need for this to be configurable.
$ENV{PG_ROOT} = $main::dirname . '/PG';
$ENV{PG_ROOT} = $main::libname . '/PG';

# Used for reconstructing library paths from sym-links.
$ENV{OPL_DIRECTORY} = "webwork-open-problem-library";
$ENV{OPL_DIRECTORY} = "$ENV{RENDER_ROOT}/webwork-open-problem-library";

$ENV{MOJO_CONFIG} = (-r "$ENV{RENDER_ROOT}/render_app.conf") ? "$ENV{RENDER_ROOT}/render_app.conf" : "$ENV{RENDER_ROOT}/render_app.conf.dist";
# $ENV{MOJO_MODE} = 'production';
# $ENV{MOJO_LOG_LEVEL} = 'debug';
}

use lib "$main::dirname";
print "home directory " . $main::dirname . "\n";
use lib "$main::libname";
print "using root directory: $ENV{RENDER_ROOT}\n";

use RenderApp::Model::Problem;
use RenderApp::Controller::RenderProblem;
use RenderApp::Controller::IO;
use WeBWorK::RenderProblem;
use WeBWorK::FormatRenderedProblem;

sub startup {
my $self = shift;
Expand All @@ -40,16 +41,12 @@ sub startup {
$ENV{$_} //= $self->config($_);
};

$ENV{baseURL} = '' if ( $ENV{baseURL} eq '/' );
$ENV{SITE_HOST} =~ s|/$||; # remove trailing slash

# $r needs to be defined before the SITE_HOST is added to the baseURL
sanitizeHostURLs();
# baseURL sets the root at which the renderer is listening, and is used in Environment for pg_root_url
my $r = $self->routes->under($ENV{baseURL});

# while iFrame embedded problems are likely to need the baseURL to include SITE_HOST
# convert to absolute URLs
$ENV{baseURL} = $ENV{SITE_HOST} . $ENV{baseURL} unless ( $ENV{baseURL} =~ m|^https?://| );
$ENV{formURL} = $ENV{baseURL} . $ENV{formURL} unless ( $ENV{formURL} =~ m|^https?://| );
print "Renderer is based at $main::basehref\n";
print "Problem attempts will be sent to $main::formURL\n";

# Handle optional CORS settings
if (my $CORS_ORIGIN = $self->config('CORS_ORIGIN')) {
Expand All @@ -66,6 +63,7 @@ sub startup {
$self->helper(newProblem => sub { shift; RenderApp::Model::Problem->new(@_) });

# Helpers
$self->helper(format => sub { WeBWorK::FormatRenderedProblem::formatRenderedProblem(@_) });
$self->helper(validateRequest => sub { RenderApp::Controller::IO::validate(@_) });
$self->helper(parseRequest => sub { RenderApp::Controller::Render::parseRequest(@_) });
$self->helper(croak => sub { RenderApp::Controller::Render::croak(@_) });
Expand Down Expand Up @@ -107,20 +105,30 @@ sub startup {
$r->any('/pg_files/CAPA_Graphics/*static')->to('StaticFiles#CAPA_graphics_file');
$r->any('/pg_files/tmp/*static')->to('StaticFiles#temp_file');
$r->any('/pg_files/*static')->to('StaticFiles#pg_file');
$r->any('/*static')->to('StaticFiles#public_file');
}

# any other requests fall through
$r->any('/*fail' => sub {
my $c = shift;
my $report = $c->stash('fail')."\nCOOKIE:";
for my $cookie (@{$c->req->cookies}) {
$report .= "\n".$cookie->to_string;
}
$report .= "\nFORM DATA:";
foreach my $k (@{$c->req->params->names}) {
$report .= "\n$k = ".join ', ', @{$c->req->params->every_param($k)};
}
$c->log->fatal($report);
$c->rendered(404)});
sub sanitizeHostURLs {
$ENV{baseURL} = "/$ENV{baseURL}";
warn "*** Configuration error: baseURL should not end in a slash\n" if $ENV{baseURL} =~ s!/$!!;
warn "*** Configuration error: baseURL should begin with a slash\n" unless $ENV{baseURL} =~ s!^//!/!;
Comment on lines +113 to +114
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

These warnings are displayed if $ENV{baseURL} is the empty string. I think that is supported, so some care is needed to prevent those warnings in that case.


# set an absolute base href for iframe embedding
my $basehref = $ENV{baseURL} =~ m!/$! ? $ENV{baseURL} : "$ENV{baseURL}/";
my $baseURL = Mojo::URL->new($basehref);
$main::basehref = $baseURL->is_abs
? $baseURL
: Mojo::URL->new($ENV{SITE_HOST})->path($baseURL);

# respect absolute form URLs for man-in-the-middle implementations
warn "*** Configuration error: formURL should not begin with a slash\n" if $ENV{formURL} =~ s!^/!!;
my $renderEndpoint = $ENV{formURL} || 'render-api';
my $formURL = Mojo::URL->new($renderEndpoint);
warn "*** Possible configuration error: are you sure you want to use $main::basehref$renderEndpoint as the render endpoint?\n"
unless $formURL->is_abs || $renderEndpoint eq 'render-api';
$main::formURL = $formURL->is_abs
? $formURL
: Mojo::URL->new($ENV{SITE_HOST})->path($basehref.$renderEndpoint);
}

1;
Loading