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"
}
}
```
### Standalone
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](#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.
### With XSUAA
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).
### With Real HTML5 Repo
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](#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.
### With Mock FLP
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.
### With Relative URIs
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.
### With Custom UI5 Configuration
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 `