@sap/html5-repo-mock

HTML5 Repo Mock
===============

HTML5 Repo Mock is a development web server that allows to run [AppRouter][1] based
application that intend to serve files from HTML5 Application Repository in non-CF
environment (e.g personal workstation, docker or K8S) the very same way as it would
run in CF.

Form AppRouter point of view, there is no difference between real HTML5 Repo and
it's mock. Both of them are business services that expose all relevant information
required by AppRouter via service binding (available via VCAP_SERVICES environment
variable).

With HTML5 Repo Mock it is also possible to serve multiple HTML5 applications and
navigate between them.

HTML5 Repo Mock is capable to resolve HTML5 application default version, which allows
accessing HTML5 applications without specifying the version.

Getting Started

1. Download or clone current repository
2. Install dependencies npm install
3. Run MOCK_DIR=test/applications node lib/index.js
4. Open http://localhost:5000/app/index.html

Usage

HTML5 Repo Mock main usage scenario is to enable preview of HTML5 modules of MTA without deploying it.
There are multiple development flows that HTML5 Repo Mock supports, and they are described in the
following sub-sections. All flows below assume MTA project with at least AppRouter and HTML5 module.

__package.json of AppRouter application__
``json
{
...
"devDependencies": {
"html5-repo-mock": "*"
},
"scripts": {
...
"start-local": "node node_modules/@sap/html5-repo-mock/index.js"
}
}
`

$3

Developer created MTA project with AppRouter and HTML5 module. There are no provisioned CF
services available yet. Developer would like to preview the UI only.

In this scenario HTML5 Repo Mock serves as both HTML5 Repo and XSUAA. It will start AppRouter
with VCAP_SERVICES described in Default VCAP_SERVICES section.
During startup, AppRouter will call http://localhost:5001/oauth/token to obtain JWT of
HTML5 Repo Mock and will use it with all followup requests.

__Mock Token__

`json
{
"access_token": "MOCK.ACCESS.TOKEN",
"token_type": "bearer",
"expires_in": 43199,
"scope": "uaa.resource",
"jti": "915f7795bf2f4ea5a77b138dc8a50709"
}
`

This scenario is good to start with, since it requires minimum effort, but is not suitable
for cases where there are scope constraints defined on routes in xs-app.json and for
cases where some HTML5 atrifacts are not part of the project (e.g. reuse libraries).
Consumption of business services and destination service subaccount level destinations
is also not possible using this approach.

$3

In case developer would like to test behaviour of HTML5 application with real XSUAA, for example
to test error handling for users with not sufficient permissions, it is possible to define
VCAP_SERVICES environment variable that contains XSUAA binding information. In this case
HTML5 Repo Mock will merge binding information of HTML5 Repo Mock into provided VCAP_SERVICES
and run AppRouter with both of them. This allows to define routes with scope constraints in
xs-app.json

`json
{
"routes": [{
"source": "^(.*)$",
"target": "$1",
"service": "html5-apps-repo-rt",
"scope": ["$XSAPPNAME.Read", "$XSAPPNAME.Write"]
}]
}
`

Also providing XSUAA credentials allows to consume business services and subaccount level
destinations, binding information of which should also be passed via VCAP_SERVICES.

`json
{
"routes": [{
"source": "^/dest/(.*)$",
"target": "$1",
"destination": "DESTINATION_NAME"
}, {
"source": "^(.*)$",
"target": "$1",
"service": "some-business-service",
"endpoint": "v1"
}]
}
`

Disadvantage of this approach is that it still does not allow to consume HTML5 applications
outside of the project (e.g. business service UIs).

$3

If HTML5 module depends on some reusable library, which is deployed to real HTML5 Repo, it
is required to use both: real HTML5 Repo and the HTML5 Repo Mock. To enable this scenario,
binding information of real HTML5 Repo may be defined in VCAP_SERVICES environment variable.
HTML5 Repo Mock will replace it with Default VCAP_SERVICES before
running AppRouter. In addition, it will fallback to real HTML5 Repo in case no matching HTML5
application is found in local environment.

This approach allows consuming not only applications from current project, but also UIs of
business services and reuse libraries. This scenario may also be mixed with XSUAA.

$3

If there are multiple HTML5 applications it is beneficial to have a dashboard with links
pointing to each one of them. In production it is usually done with Portal Service (aka FLP).

HTML5 Repo Mock may provide similar capabilities by utilizing "Fiori Sandbox" environment, which
provides FLP-like experience and display tiles pointing to applications in local environment.

To enable FLP Mock, --flp flag should be passed as command line argument to HTML5 Repo Mock.

$3

If target platform to which HTML5 application will be deployed is not Cloud Foundry, it may be
required to set absolute paths (e.g. /sap/opu/odata/snce/PO_S_SRV;v=2/) in manifest.json data
source URIs. This makes impossible to test these applications with HTML5 Repo Mock, because it
will treat first segment of the data source path as application name. To solve the issue,
without modifying source code for testing purposes, the --relative flag is supported by HTML5
Repo Mock. Once it is set, HTML5 Repo Mock will remove leading slashes from all data source
URIs, when serving manifest.json files.

To enable relative URIs, --relative flag should be passed as command line argument to
HTML5 Repo Mock.

$3

In case some of SAP UI5 bootstrap configuration should be overridden, it is possible to specify
--ui5 command line argument to the HTML5 Repo Mock in the following format:

`json
{"version": "1.72.0", "theme": "sap_belize"}
`

The version will be inserted before /resources in all URLs appearing in HTML file that have
the same origin as