add documentation, wire configuration

changelog/unreleased/enhancement-add-open-with-web-endpoint.md

@@ -0,0 +1,7 @@
+Enhancement: Add /app/open-with-web endpoint
+
+We've added an /app/open-with-web endpoint to the app provider, so that
+clients that are no browser or have only limited browser access can also open apps with the help of a Web URL.
+
+https://github.com/owncloud/ocis/pull/4376
+https://github.com/cs3org/reva/pull/3143

docs/services/app-registry/apps.md

@@ -25,7 +25,7 @@ The capabilities endpoint (e.g. `https://localhost:9200/ocs/v1.php/cloud/capabil
               "version": "1.1.0",
               "apps_url": "/app/list",
               "open_url": "/app/open",
-              "open_web_url": "/app/open-in-web",
+              "open_web_url": "/app/open-with-web",
               "new_url": "/app/new"
             }
           ]
@@ -179,6 +179,48 @@ HTTP status code: 200
 }
 ```
 
+### Open a file with the ownCloud Web
+
+**Endpoint**: specified in the capabilities in `open_web_url`, currently `/app/open-with-web`
+
+**Method**: HTTP POST
+
+**Authentication** (one of them):
+
+- `Authorization` header with OIDC Bearer token for authenticated users or basic auth credentials (if enabled in oCIS)
+- `X-Access-Token` header with a REVA token for authenticated users
+
+**Query parameters**:
+
+- `file_id` (mandatory): id of the file to be opened
+- `app_name` (optional)
+  - default (not given): default app for mime type
+  - possible values depend on the app providers for a mimetype from the `/app/open` endpoint
+
+**Request examples**:
+
+```bash
+curl -X POST 'https://ocis.test/app/open?file_id=ZmlsZTppZAo='
+
+curl -X POST 'https://ocis.test/app/open?file_id=ZmlsZTppZAo=&app_name=Collabora'
+```
+
+**Response examples**:
+
+The URI from the response JSON is intended to be opened with a GET request in a browser. If the user has not yet a session in the browser, a login flow is handled by ownCloud Web.
+
+HTTP status code: 200
+
+```json
+{
+  "uri": "https://....."
+}
+```
+
+**Example responses (error case)**:
+
+See error cases for [Open a file with the app provider](#open-a-file-with-the-app-provider)
+
 ### Open a file with the app provider
 
 **Endpoint**: specified in the capabilities in `open_url`, currently `/app/open`

services/frontend/pkg/command/server.go

@@ -48,7 +48,10 @@ func Server(cfg *config.Config) *cli.Command {
 
 			pidFile := path.Join(os.TempDir(), "revad-"+cfg.Service.Name+"-"+uuid.Must(uuid.NewV4()).String()+".pid")
 
-			rcfg := revaconfig.FrontendConfigFromStruct(cfg)
+			rcfg, err := revaconfig.FrontendConfigFromStruct(cfg)
+			if err != nil {
+				return err
+			}
 
 			gr.Add(func() error {
 				runtime.RunWithOptions(rcfg, pidFile, runtime.WithLogger(&logger.Logger))

services/frontend/pkg/revaconfig/config.go

@@ -1,6 +1,7 @@
 package revaconfig
 
 import (
+	"net/url"
 	"path"
 	"strconv"
 
@@ -9,7 +10,15 @@ import (
 )
 
 // FrontendConfigFromStruct will adapt an oCIS config struct into a reva mapstructure to start a reva service.
-func FrontendConfigFromStruct(cfg *config.Config) map[string]interface{} {
+func FrontendConfigFromStruct(cfg *config.Config) (map[string]interface{}, error) {
+
+	webURL, err := url.Parse(cfg.PublicURL)
+	if err != nil {
+		return map[string]interface{}{}, err
+	}
+	webURL.Path = "/external"
+	webOpenInAppURL := webURL.String()
+
 	archivers := []map[string]interface{}{
 		{
 			"enabled":       true,
@@ -27,7 +36,7 @@ func FrontendConfigFromStruct(cfg *config.Config) map[string]interface{} {
 			"version":      "1.1.0",
 			"apps_url":     "/app/list",
 			"open_url":     "/app/open",
-			"open_web_url": "/app/open-in-web",
+			"open_web_url": "/app/open-with-web",
 			"new_url":      "/app/new",
 		},
 	}
@@ -89,15 +98,16 @@ func FrontendConfigFromStruct(cfg *config.Config) map[string]interface{} {
 					"transfer_shared_secret": cfg.TransferSecret,
 					"timeout":                86400,
 					"insecure":               cfg.AppHandler.Insecure,
-					"webbaseuri":             "https://ocis.owncloud.test/external",
+					"webbaseuri":             webOpenInAppURL,
 					"web": map[string]interface{}{
 						"urlparamsmapping": map[string]string{
 							// param -> value mapper
+							// these mappers are static and are only subject to change when changed in oC Web
 							"fileId": "fileid",
 							"app":    "appname",
 						},
 						"staticurlparams": map[string]string{
-							"contextRouteName": "files-spaces-personal",
+							"contextRouteName": "files-spaces-personal", // TODO: remove when https://github.com/owncloud/web/pull/7437 arrived in oCIS
 						},
 					},
 				},
@@ -239,5 +249,5 @@ func FrontendConfigFromStruct(cfg *config.Config) map[string]interface{} {
 				},
 			},
 		},
-	}
+	}, nil
 }