Add custom routes to pages router

[mtrezza]

New Pull Request Checklist

• I am not disclosing a vulnerability.
• I am creating this PR in reference to an issue.

Issue Description

Currently, the experimental PagesRouter does not allow to add custom routes.

Related issue: closes #7230

Approach

Add Parse Server option pages.customRoutes to define custom routes that are then auto-mounted by the PagesRouter.

Example:

pages.customRoutes: [
    {
      method: 'GET',
      path: 'custom_route',
      handler: async req => {
        // some custom logic
        // ...
        // then, depending on the outcome, return a HTML file as response
        return { file: 'custom_page.html' };
      },
    },
]

The above route can be invoked by requesting https://example.com/[mount]/apps/[appId]/custom_page.

The returned file enjoys all the internal logic that is also used by the feature pages (e.g password reset) such as localization, and custom placeholders.

Note: This feature is only implemented in the still experimental PagesRouter which is expected to deprecate the PublicAPIRouter in the future.

Side effects

• Fixed bug in Parse Server definitions builder that did not support the type "array of custom type"

TODOs before merging

• Add test cases
• Add config param validation + tests
• Add entry to changelog
• Add changes to documentation (guides, repository pages, in-code descriptions)

[codecov]

Codecov Report

Merging #7231 (ee2a11a) into master (cac6951) will increase coverage by 0.03%.
The diff coverage is 100.00%.

@@            Coverage Diff             @@
##           master    #7231      +/-   ##
==========================================
+ Coverage   94.00%   94.03%   +0.03%     
==========================================
  Files         172      172              
  Lines       12955    12970      +15     
==========================================
+ Hits        12178    12196      +18     
+ Misses        777      774       -3     

Impacted Files	Coverage Δ
src/Options/index.js	100.00% <ø> (ø)
src/Config.js	93.02% <100.00%> (+0.13%)	⬆️
src/Options/Definitions.js	100.00% <100.00%> (ø)
src/Routers/PagesRouter.js	97.70% <100.00%> (+0.11%)	⬆️
src/Adapters/Storage/Mongo/MongoStorageAdapter.js	92.92% <0.00%> (+0.66%)	⬆️

---

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update cac6951...54ce26d. Read the comment docs.

[mtrezza]

This is ready for review; a good place to get familiar with this feature is to read the added docs in the README.

[davimacedo]

@mtrezza thanks for the PR! I'd like to better understand the problem that this feature solves. What would be the benefit of using the custom route instead of just mounting a new endpoint in the Express.js app?

[mtrezza]

@davimacedo Sure, this is mostly a forward-looking PR, because it provides the basis to make future features available to all custom routes by just adding a feature to the PagesRouter.

But there are already some benefits in this first version:

• These custom routes are invoked with the same familiar URL patterns as the password reset, email verification built-in routes, so the URL includes the app ID. That means all default placeholders like appName, appId, parseServerPublicUrl are automatically available inside the HTML page. While this can already be achieved with the PagesRouter's custom placeholders feature, the custom route of this PR doesn't require the developer to write additional code to make these placeholders available. That means custom routes make it easy to create HTML forms that post to another custom route, like chaining.
• Custom routes can get more abstracted in the future to become like a toolbox to create the above mentioned chains even easier and with more convenience features, which means less code for developers.
• The custom routes are mounted after the built-in routes like password reset. That means a custom route can not accidentally "steal" a request from a built-in route, because requests always are first passed to the built-in routes for a possible match.
• As the PagesRouter gets new features in the future, they can also be made be available to custom routes, because they are part of the router. For example:
  • Add a feature that logs a warning if a custom route overlaps with a built-in route that uses the same endpoint.
  • Add convenience return values for custom route, currently it is only a webpage, but this can be abstracted and extended further.
  • Add interface to directly override built-in routes with custom routes.
• I could see the PagesRouter in the future extending its role in Parse Server, for centralized 404, 500 response handling. The custom routes interface may also be used internally by Parse Server for that reason, but that's still a vague idea.

[davimacedo]

I am in for this new feature in Parse Server. @dplewis thoughts?

[dplewis]

Looks good! Just a quick comment.

[mtrezza]

@dplewis Thanks, this is ready for review

[mtrezza]

If there is no objection, I'll merge this later today; this also fixes an issue with the config definitions builder (described above) which I again stumble upon in another PR.

[parseplatformorg]

🎉 This change has been released in version 5.0.0-beta.1

[parseplatformorg]

🎉 This change has been released in version 5.0.0