From 15080fc5e6cb35d31cca7ca97615874c034d5899 Mon Sep 17 00:00:00 2001 From: Willy Kloucek Date: Tue, 15 Jun 2021 12:20:22 +0200 Subject: [PATCH 1/9] wip: extension development --- docs/ocis/development/extensions.md | 231 ++++------------------------ 1 file changed, 31 insertions(+), 200 deletions(-) diff --git a/docs/ocis/development/extensions.md b/docs/ocis/development/extensions.md index 7f8815e3d8..034e48e538 100644 --- a/docs/ocis/development/extensions.md +++ b/docs/ocis/development/extensions.md @@ -7,227 +7,58 @@ geekdocEditPath: edit/master/docs/ocis/development geekdocFilePath: extensions.md --- -{{< toc >}} +oCIS is all about files, sync and share - but most of the time there is some more you want to do with your files, eg. have a different view on your photo collection or edit your office file in an online file editor. ownCloud 10 faced the same problems and tries to solve them with so called "apps". These can extend the functionality of ownCloud 10 in a wide range. oCIS has a similar concept to be extended in its functionality: extensions. Because oCIS is very different in its architecture compared to ownCloud 10 this also applies to the extensions. An extension is basically any running code which satisfies basic interfaces and provides functionality to oCIS and its users. Because extensions are micro services you can choose almost any programming language you like. (even if for some languages the task might be a lot easier - but for ownCloud 10 it was nearly impossible to use a different programming language than php). -## How to build and run ocis-simple +We will now introduce you to concepts, possibilities and ... of the oCIS extension system. -oCIS uses build tags to build different flavors of the binary. In order to work on a new extension we are going to reduce the scope a little and use the `simple` tag. Let us begin by creating a dedicated folder: -```console -mkdir ocis-extension-workshop && ocis-extension-workshop -``` -Following https://github.com/owncloud/ocis +### Extensions outside of the oCIS Monorepo +Technically every service in oCIS is an extension, even if oCIS would not really work without them. So there are plenty of extensions which you can have a look at in the oCIS Monorepo. -```console -git clone https://github.com/owncloud/ocis.git -cd ocis +Besides these "default" extensions there are also some more extensions: -TAGS=simple make generate build -``` +- Hello +- WOPI server -*Q: Can you specify which version of ownCloud Web to use?* -*A: No, the ownCloud Web that is used is compiled into the [assets of ocis-web](https://github.com/owncloud/ocis/blob/master/web/pkg/assets/embed.go) which is currently not automatically updated. We'll see how to use a custom ownCloud Web later.* +Difference between extensions living inside the oCIS monorepo and in its own repo are: +- extensions inside the oCIS monorepo are all written in Go, whereas other extensions may choose the programming language freely +- extension inside the oCIS monorepo share tooling, whereas other extensions may use different tooling (eg. a different CI system) +- extensions inside the oCIS monorepo will be all build into one binary and started with the `ocis server` command. Other extensions must be started individually. -`bin/ocis server` -Open the browser at https://localhost:9200 -1. You land on the login screen. click login -2. You are redirected to an idp at https://localhost:9200/signin/v1/identifier with a login mask. Use `einstein:relativity` (one of the three demo users) to log in -3. You are redirected to http://localhost:9100/#/hello the ocis-hello app -4. Replace `World` with something else and submit. You should see `Hello %something else%` +### Web +- App +- Design System -*Q: One of the required ports is already in use. Ocis seems to be trying to restart the service over and over. What gives?* -*A: Using the ocis binary to start the server will case ocis to keep track of the different services and restart them in case they crash.* +### Settings +An extension likely has some behaviour which the user can configure. Fundamental configuration will often be done by admins during deploy time in configuration files or by environment variables. But for other settings - which are supposed to change more often or which are even user specific - this is not a viable way. Therefore you need to offer the users a UI where they can configure your extension to their liking. Because implementing something like this is a repetitive task among extensions, oCIS already offers the settings extensions which does that for your extension. Your extension just needs to register settings bundles and permissions and read the current values from the settings service. You can read more on that on [Settings Extensions]({{< ref "../../extensions/settings" >}}) and see how [oCIS Hello uses settings](). -## Hacking ocis-hello +### Proxy +The Proxy acts as an API gateway and is the single connection point where all request from users and devices are sent to. -go back to the ocis-extension-workshop folder +In order that requests can reach your extensions' api you need to register one or multiple endpoints at the proxy. This is currently done by manually adding routes to a config file but will be done dynamically by service discovery in the future. The registration is a easy task and can be seen best on the [oCIS Hello example](). -```console -cd .. -``` +As files you store in your ownCloud must always stay private unless you share them with your friends or coworkers, requests to oCIS have always a user context. This user context is also available to your extension and can be used to interact with the users' files. How to get the user context and authentication can be seen bet on the [oCIS Hello example]() or the [WOPI server example](). -Following https://github.com/owncloud/ocis-hello -``` -git clone https://github.com/owncloud/ocis-hello.git -cd ocis-hello -yarn install -# this actually creates the assets -yarn build +### Storage +oCIS leverages the CS3 APIs and REVA as a storage system because it offers a very flexible setup and supports a variety of storage backends like EOS, S3 and of course your local hard disk. REVA makes it easy to support more storage backends as needed. -# this will compile the assets into the binary -make generate build -``` +If you need to interact with files, you have the full power of the [CS3 APIs]() in your hand. With the user context and authorization your extensions gets from the proxy you can make these request in behalf of the user. -Two options: -1. run only the necessary services from ocis and ocis-hello independently -2. compile ocis with the updated ocis-hello +If your extension needs to store data which is not supposed to life in the users home folder, there is also so called metadata storage which can be used for that purpose. -### Option 1: -get a list of ocis services: +They main point you should get about storage in an oCIS extension is that you should never use the filesystem, but always use the CS3 APIs. -```console -ps ax | grep ocis -``` +### Deployment -Try to kill `ocis hello` -Remember: For now, killing a service will cause ocis to restart it. This is subject to change. +### Outstanding development -In order to be able to manage the processes ourselves we need to start them independently: - -`bin/ocis server` starts the same services as: - -``` -bin/ocis micro & -bin/ocis web & -bin/ocis hello & -bin/ocis reva & -``` - -Now we can kill the `ocis hello` and use our custom built ocis-hello binary: - -```console -cd ../ocis-hello -bin/ocis-hello server -``` - -## Hacking ownCloud Web (and ocis-web) - -Following https://github.com/owncloud/web we are going to build the current ownCloud Web - -``` -git clone https://github.com/owncloud/web.git -cd web - -yarn install -yarn dist -``` - -We can tell ocis to use the compiled assets: - -Kill `ocis web`, then use the compiled assets when starting ownCloud Web. - -```console -cd ../ocis -WEB_ASSET_PATH="`pwd`/../web/dist" bin/ocis web -``` - -## The ownCloud design system - -The [ownCloud design system](https://owncloud.design/) contains a set of ownCloud vue components for ownCloud Web or your own ocis extensions. Please use it for a consistent look and feel. - -## External ownCloud Web apps - -This is what hello is: copy and extend! - -1. ownCloud Web is configured using the config.json which is served by the ocis-web service (either `bin/ocis web` or `bin/web server`) - -2. point ocis-web to the web config which you extended with an external app: -`WEB_UI_CONFIG="`pwd`/../web/config.json" ASSET_PATH="`pwd`/../web/dist" bin/ocis web` - -```json -{ - "server": "https://localhost:9200", - "theme": "owncloud", - "version": "0.1.0", - "openIdConnect": { - "metadata_url": "https://localhost:9200/.well-known/openid-configuration", - "authority": "https://localhost:9200", - "client_id": "web", - "response_type": "code", - "scope": "openid profile email" - }, - "apps": [], - "external_apps": [ - { - "id": "hello", - "path": "http://localhost:9105/hello.js", - "config": { - "url": "http://localhost:9105" - } - }, - { - "id": "myapp", - "path": "http://localhost:6789/superapp.js", - "config": { - "backend": "http://someserver:1234", - "myconfig": "is awesome" - } - } - ] -} -``` - -## ownCloud Web extension points - -{{< hint info >}} -For an up to date list check out [the ownCloud Web documentation](https://github.com/owncloud/web/issues/2423). -{{< /hint >}} - -Several ones available: - -### ownCloud Web -- App switcher (defined in config.json) -- App container (loads UI of your extension) - -### Files app -- File action -- Create new file action -- Sidebar -- Quick access for sidebar inside of file actions (in the file row) - -Example of a file action in the `app.js`: -```js -const appInfo = { - name: 'MarkdownEditor', - id: 'markdown-editor', - icon: 'text', - isFileEditor: true, - extensions: [{ - extension: 'txt', - newFileMenu: { - menuTitle ($gettext) { - return $gettext('Create new plain text file…') - } - } - }, - { - extension: 'md', - newFileMenu: { - menuTitle ($gettext) { - return $gettext('Create new mark-down file…') - } - } - }] -} -``` - -For the side bar have a look at the files app, `defaults.js` & `fileSideBars` - -## API driven development - -Until now we only had a look at the ui and how the extensions are managed on the cli. But how do apps actually talk to the server? - -Short answer: any way you like - -Long answer: micro and ocis-hello follow a protocol driven development: - -- specify the API using protobuf -- generate client and server code -- evolve based on the protocol - -- CS3 api uses protobuf as well and uses GRPC - -- ocis uses go-micro, which provides http and grpc gateways -- the gateways and protocols are optional - -- owncloud and kopano are looking into a [MS graph](https://developer.microsoft.com/de-de/graph) like api to handle ownCloud Web requests. - - they might be about user, contacts, calendars ... which is covered by the graph api - - we want to integrate with eg. kopano and provide a common api (file sync and share is covered as well) - -- as an example for protobuf take a look at [ocis-hello](https://github.com/owncloud/ocis-hello/tree/master/pkg/proto/v0) +- dynamic registration web / proxy +- entitle service to act in behalf of users without request +- access to metadata storage +- Events (eg. callbacks on file create/change/delete events) From 757caa428725463ac0076afaa101efae0661a7c0 Mon Sep 17 00:00:00 2001 From: Willy Kloucek Date: Tue, 15 Jun 2021 13:44:55 +0200 Subject: [PATCH 2/9] add links --- docs/ocis/development/extensions.md | 78 +++++++++++++++++------------ 1 file changed, 45 insertions(+), 33 deletions(-) diff --git a/docs/ocis/development/extensions.md b/docs/ocis/development/extensions.md index 034e48e538..bbf037950a 100644 --- a/docs/ocis/development/extensions.md +++ b/docs/ocis/development/extensions.md @@ -7,58 +7,70 @@ geekdocEditPath: edit/master/docs/ocis/development geekdocFilePath: extensions.md --- -oCIS is all about files, sync and share - but most of the time there is some more you want to do with your files, eg. have a different view on your photo collection or edit your office file in an online file editor. ownCloud 10 faced the same problems and tries to solve them with so called "apps". These can extend the functionality of ownCloud 10 in a wide range. oCIS has a similar concept to be extended in its functionality: extensions. Because oCIS is very different in its architecture compared to ownCloud 10 this also applies to the extensions. An extension is basically any running code which satisfies basic interfaces and provides functionality to oCIS and its users. Because extensions are micro services you can choose almost any programming language you like. (even if for some languages the task might be a lot easier - but for ownCloud 10 it was nearly impossible to use a different programming language than php). +oCIS is all about files, sync and share - but most of the time there is more you want to do with your files, eg. have a different view on your photo collection or edit your offices files in an online file editor. ownCloud 10 faced the same problem and solved them with applications. These can extend the functionality of ownCloud 10 in a wide range. oCIS has a similar concept to be extended in its functionality: extensions. Because oCIS is different in its architecture compared to ownCloud 10, this also applies to the extensions. An extension is basically any running code which integrates into oCIS and provides functionality to oCIS and its users. Because extensions are just microservices providing an API, you can choose almost any programming language you like. For some languages the task might be a lot easier, but for ownCloud 10 it was nearly impossible to use a different programming language than PHP. -We will now introduce you to concepts, possibilities and ... of the oCIS extension system. +We will now introduce you to the oCIS extension system and how you can use it for your extension. + +## Extension examples + +Technically every service in oCIS is an extension, even if oCIS would not really work without some of them. So there are plenty of extensions which you can have a look at in the [oCIS monorepo](https://github.com/owncloud/ocis). + +Besides these "default" extensions in the oCIS monorepo there are more extensions: + +- [Hello](https://github.com/owncloud/ocis-hello) +- [WOPI server](https://github.com/owncloud/ocis-wopiserver) + +Differences between extensions maintained inside the oCIS monorepo and ones maintained in their own repository are: + +- extensions inside the [oCIS monorepo](https://github.com/owncloud/ocis) are all written in Go, whereas other extensions may choose the programming language freely +- extension inside the oCIS monorepo heavily share tooling to reduce maintenance efforts, whereas other extensions may use different tooling (eg. a different CI system) +- extensions inside the oCIS monorepo will be all build into one binary and started with the `ocis server` command. All other extensions must be started individually besides oCIS. - -### Extensions outside of the oCIS Monorepo -Technically every service in oCIS is an extension, even if oCIS would not really work without them. So there are plenty of extensions which you can have a look at in the oCIS Monorepo. - -Besides these "default" extensions there are also some more extensions: - -- Hello -- WOPI server - -Difference between extensions living inside the oCIS monorepo and in its own repo are: -- extensions inside the oCIS monorepo are all written in Go, whereas other extensions may choose the programming language freely -- extension inside the oCIS monorepo share tooling, whereas other extensions may use different tooling (eg. a different CI system) -- extensions inside the oCIS monorepo will be all build into one binary and started with the `ocis server` command. Other extensions must be started individually. +For quickstart purposes we also offer a [template project](https://github.com/owncloud/boilr-ocis-extension) which can be used to generate all the boilerplate code for you. But you also can decide to use your own project layout or even a different programming language. +## Integration into oCIS -### Web -- App -- Design System +Depending on the functionality of your extension you might need to integrate with one or more components of oCIS mentioned below. + +### ownCloud Web + +If your extension is not just doing something in the background, you will need a UI in order to allow the user to interact with your extension. You could just provide your own web frontend for that purpose but for a better user experience you need to integrate in the web frontend of oCIS, [ownCloud Web](https://github.com/owncloud/web). + +ownCloud Web allows you to write an extension to itself and offers therefore a seamless user experience. The user will be able to use the application switcher to switch between the files view, settings and available extensions. Furthermore it is also possible to register your extension for different file actions. You could offer your extension to the user for creating and editing office text documents. The user will then be able to create or open a file with your application directly from the files view. How to provide create an extension for ownCloud Web can be seen best in [the Hello extension](https://github.com/owncloud/ocis-hello/blob/master/ui/app.js), whereas plain file handling without any web frontend is available in the [WOPI server extension](https://github.com/owncloud/ocis-wopiserver/blob/master/ui/app.js). + +In order to ownCloud Web pick up your extension, you need to activate it in the configuration like seen in the [Hello extension](https://owncloud.dev/extensions/ocis_hello/running/#configure-and-start-ocis). As of now this is a manual task but later on this will be done automatically by service discovery. + +For better visual integration ownCloud Web itself uses a external design library, the [ownCloud design system](https://github.com/owncloud/owncloud-design-system). This should also be used by your extension. ### Settings -An extension likely has some behaviour which the user can configure. Fundamental configuration will often be done by admins during deploy time in configuration files or by environment variables. But for other settings - which are supposed to change more often or which are even user specific - this is not a viable way. Therefore you need to offer the users a UI where they can configure your extension to their liking. Because implementing something like this is a repetitive task among extensions, oCIS already offers the settings extensions which does that for your extension. Your extension just needs to register settings bundles and permissions and read the current values from the settings service. You can read more on that on [Settings Extensions]({{< ref "../../extensions/settings" >}}) and see how [oCIS Hello uses settings](). + +An extension likely has some behaviour which the user can configure. Fundamental configuration will often be done by admins during deploy time in configuration files or by environment variables. But for other settings, which are supposed to change more often or which are even user specific, this is not a viable way. Therefore you need to offer the users a UI where they can configure your extension to their liking. Because implementing something like this is a repetitive task among extensions, oCIS already offers the settings extensions which does that for your extension. Your extension just needs to register settings bundles, respective permissions and finally read the current values from the settings service. You can read more on that on the [settings extension]({{< ref "../../extensions/settings" >}}) and see how [oCIS Hello uses these settings](https://owncloud.dev/extensions/ocis_hello/settings/). ### Proxy -The Proxy acts as an API gateway and is the single connection point where all request from users and devices are sent to. -In order that requests can reach your extensions' api you need to register one or multiple endpoints at the proxy. This is currently done by manually adding routes to a config file but will be done dynamically by service discovery in the future. The registration is a easy task and can be seen best on the [oCIS Hello example](). - -As files you store in your ownCloud must always stay private unless you share them with your friends or coworkers, requests to oCIS have always a user context. This user context is also available to your extension and can be used to interact with the users' files. How to get the user context and authentication can be seen bet on the [oCIS Hello example]() or the [WOPI server example](). +The Proxy is an API gateway and acts as the single connection point where all external request from users and devices need to pass through. +In order that requests can reach your extensions' API you need to register one or multiple endpoints at the proxy. This is currently done by manually adding routes to a config file but will be done dynamically by service discovery in the future. The registration is a easy task and can be seen best on the [oCIS Hello example](https://owncloud.dev/extensions/ocis_hello/running/#configure-and-start-ocis). +As files in ownCloud must always stay private, unless you share them with your friends or coworkers, requests to oCIS have always a authenticated user context. This user context is also available to your extension and can be used to interact with the users' files. How to get the user context and authentication can be seen on the [oCIS Hello example](https://owncloud.dev/extensions/ocis_hello/settings/#account-uuid). ### Storage -oCIS leverages the CS3 APIs and REVA as a storage system because it offers a very flexible setup and supports a variety of storage backends like EOS, S3 and of course your local hard disk. REVA makes it easy to support more storage backends as needed. -If you need to interact with files, you have the full power of the [CS3 APIs]() in your hand. With the user context and authorization your extensions gets from the proxy you can make these request in behalf of the user. +oCIS leverages the CS3 APIs and [CS3 REVA](https://github.com/cs3org/reva) as a storage system because it offers a very flexible setup and supports a variety of storage backends like EOS, S3 and of course your local hard drive. REVA makes it easy to support more storage backends as needed. -If your extension needs to store data which is not supposed to life in the users home folder, there is also so called metadata storage which can be used for that purpose. +If you need to interact with files directly, you have the full power of the [CS3 APIs](https://cs3org.github.io/cs3apis/) in your hand. With the user context and the users' authentication token, which your extensions gets from the proxy, your extension can make these request in behalf of the user. -They main point you should get about storage in an oCIS extension is that you should never use the filesystem, but always use the CS3 APIs. +If your extension needs to store data which is not supposed to life in the users home folder, there is also so called metadata storage which can be used for that purpose without a specific user context. -### Deployment +One main point you should get about storage in an oCIS extension is that you should never use the filesystem, but always use the CS3 APIs. +## Development Roadmap -### Outstanding development +When reading the above section you might have noticed, that some integrations need some manual setup as of now but we are planning to switch to automatic service discovery in a later development stage of oCIS. -- dynamic registration web / proxy -- entitle service to act in behalf of users without request -- access to metadata storage -- Events (eg. callbacks on file create/change/delete events) +There are some more topics on our roadmap for the extension system: + +- Events: allow extensions to register for some events. On occurrence of the event they will receive some kind of notification or a callback. This would for example allow your application to perform actions on the creations, modification or deletion of a file. +- Entitlement of extensions to act in behalf of users without a request context: user should be able to grant and revoke extensions access to their files even in behalf of them eg. in the background. From 2e7741294180f60b27dd844dd9320e2a2ceada14 Mon Sep 17 00:00:00 2001 From: Willy Kloucek <34452982+wkloucek@users.noreply.github.com> Date: Wed, 16 Jun 2021 08:53:23 +0200 Subject: [PATCH 3/9] Apply suggestions from code review Co-authored-by: Pascal Wengerter --- docs/ocis/development/extensions.md | 30 ++++++++++++++--------------- 1 file changed, 15 insertions(+), 15 deletions(-) diff --git a/docs/ocis/development/extensions.md b/docs/ocis/development/extensions.md index bbf037950a..5570d843eb 100644 --- a/docs/ocis/development/extensions.md +++ b/docs/ocis/development/extensions.md @@ -7,23 +7,23 @@ geekdocEditPath: edit/master/docs/ocis/development geekdocFilePath: extensions.md --- -oCIS is all about files, sync and share - but most of the time there is more you want to do with your files, eg. have a different view on your photo collection or edit your offices files in an online file editor. ownCloud 10 faced the same problem and solved them with applications. These can extend the functionality of ownCloud 10 in a wide range. oCIS has a similar concept to be extended in its functionality: extensions. Because oCIS is different in its architecture compared to ownCloud 10, this also applies to the extensions. An extension is basically any running code which integrates into oCIS and provides functionality to oCIS and its users. Because extensions are just microservices providing an API, you can choose almost any programming language you like. For some languages the task might be a lot easier, but for ownCloud 10 it was nearly impossible to use a different programming language than PHP. +oCIS is all about files, sync and share - but most of the time there is more you want to do with your files, e.g. having a different view on your photo collection or editing your offices files in an online file editor. ownCloud 10 faced the same problem and solved them with applications, which can extend the functionality of ownCloud 10 in a wide range. oCIS has a similar concept to be extended in its functionality: Extensions. Because oCIS is different in its architecture compared to ownCloud 10, this also applies to the extensions. An extension is basically any running code which integrates into oCIS and provides functionality to oCIS and its users. Because extensions are just microservices providing an API, you can technically choose any programming language you like - a huge improvement to ownCloud 10, where it was nearly impossible to use a different programming language than PHP. We will now introduce you to the oCIS extension system and how you can use it for your extension. ## Extension examples -Technically every service in oCIS is an extension, even if oCIS would not really work without some of them. So there are plenty of extensions which you can have a look at in the [oCIS monorepo](https://github.com/owncloud/ocis). +Technically every service in oCIS is an extension, even if oCIS would not really work without some of them. Therefore, you can draw inspiration from any of the plenty of extensions in the [oCIS monorepo](https://github.com/owncloud/ocis). Besides these "default" extensions in the oCIS monorepo there are more extensions: - [Hello](https://github.com/owncloud/ocis-hello) - [WOPI server](https://github.com/owncloud/ocis-wopiserver) -Differences between extensions maintained inside the oCIS monorepo and ones maintained in their own repository are: +Differences between the extensions maintained inside the oCIS monorepo and the ones maintained in their own repository are: - extensions inside the [oCIS monorepo](https://github.com/owncloud/ocis) are all written in Go, whereas other extensions may choose the programming language freely -- extension inside the oCIS monorepo heavily share tooling to reduce maintenance efforts, whereas other extensions may use different tooling (eg. a different CI system) +- extensions inside the oCIS monorepo heavily share tooling to reduce maintenance efforts, whereas other extensions may use different tooling (e.g. a different CI system) - extensions inside the oCIS monorepo will be all build into one binary and started with the `ocis server` command. All other extensions must be started individually besides oCIS. @@ -32,29 +32,29 @@ For quickstart purposes we also offer a [template project](https://github.com/ow ## Integration into oCIS -Depending on the functionality of your extension you might need to integrate with one or more components of oCIS mentioned below. +Depending on the functionality of your extension, you might need to integrate with one or multiple of the components of oCIS mentioned below. ### ownCloud Web -If your extension is not just doing something in the background, you will need a UI in order to allow the user to interact with your extension. You could just provide your own web frontend for that purpose but for a better user experience you need to integrate in the web frontend of oCIS, [ownCloud Web](https://github.com/owncloud/web). +If your extension is not just doing something in the background, you will need a UI in order to allow the user to interact with your extension. You could just provide your own web frontend for that purpose, but for a better user experience you can easily integrate into the web frontend of oCIS, the new [ownCloud Web](https://github.com/owncloud/web). -ownCloud Web allows you to write an extension to itself and offers therefore a seamless user experience. The user will be able to use the application switcher to switch between the files view, settings and available extensions. Furthermore it is also possible to register your extension for different file actions. You could offer your extension to the user for creating and editing office text documents. The user will then be able to create or open a file with your application directly from the files view. How to provide create an extension for ownCloud Web can be seen best in [the Hello extension](https://github.com/owncloud/ocis-hello/blob/master/ui/app.js), whereas plain file handling without any web frontend is available in the [WOPI server extension](https://github.com/owncloud/ocis-wopiserver/blob/master/ui/app.js). +ownCloud Web allows you to write an extension for itself and therefore offers a seamless user experience. Upon login, the user will be able to use the application switcher to switch between the files view, settings and other available and installed extensions, yours included. Furthermore it is also possible to register your extension for different file actions. As an example, you could offer your extension to the user for creating and editing office documents. The user will then be able to create or open a file with your application directly from the files view. How to provide create an extension for ownCloud Web can be seen best in [the Hello extension](https://github.com/owncloud/ocis-hello/blob/master/ui/app.js), whereas plain file handling without any web frontend is available in the [WOPI server extension](https://github.com/owncloud/ocis-wopiserver/blob/master/ui/app.js). -In order to ownCloud Web pick up your extension, you need to activate it in the configuration like seen in the [Hello extension](https://owncloud.dev/extensions/ocis_hello/running/#configure-and-start-ocis). As of now this is a manual task but later on this will be done automatically by service discovery. +To make ownCloud Web pick up your extension, you need to activate it in the configuration like seen in the [Hello extension](https://owncloud.dev/extensions/ocis_hello/running/#configure-and-start-ocis). As of now this is a manual task, but in the future this will be done automatically by service discovery. -For better visual integration ownCloud Web itself uses a external design library, the [ownCloud design system](https://github.com/owncloud/owncloud-design-system). This should also be used by your extension. +For a consistent look and feel, ownCloud Web uses a external design library, the [ownCloud design system](https://github.com/owncloud/owncloud-design-system). Since its classes and components are available through the wrapping `web runtime`, we highly recommend you to leverage it in your extension as well. ### Settings -An extension likely has some behaviour which the user can configure. Fundamental configuration will often be done by admins during deploy time in configuration files or by environment variables. But for other settings, which are supposed to change more often or which are even user specific, this is not a viable way. Therefore you need to offer the users a UI where they can configure your extension to their liking. Because implementing something like this is a repetitive task among extensions, oCIS already offers the settings extensions which does that for your extension. Your extension just needs to register settings bundles, respective permissions and finally read the current values from the settings service. You can read more on that on the [settings extension]({{< ref "../../extensions/settings" >}}) and see how [oCIS Hello uses these settings](https://owncloud.dev/extensions/ocis_hello/settings/). +An extension likely has some behaviour which the user can configure. Fundamental configuration will often be done by administrators during deployment, via configuration files or by setting environment variables. But for other settings, which are supposed to change more often or which are even user specific, this is not a viable way. Therefore you need to offer the users a UI where they can configure your extension to their liking. Because implementing something like this is a repetitive task among extensions, oCIS already offers the settings extensions which does that for your extension. Your extension just needs to register settings bundles, respective permissions and finally read the current values from the settings service. You can read more on that on the [settings extension]({{< ref "../../extensions/settings" >}}) and see how [oCIS Hello uses these settings](https://owncloud.dev/extensions/ocis_hello/settings/). ### Proxy The Proxy is an API gateway and acts as the single connection point where all external request from users and devices need to pass through. -In order that requests can reach your extensions' API you need to register one or multiple endpoints at the proxy. This is currently done by manually adding routes to a config file but will be done dynamically by service discovery in the future. The registration is a easy task and can be seen best on the [oCIS Hello example](https://owncloud.dev/extensions/ocis_hello/running/#configure-and-start-ocis). +To make sure that requests can reach your extensions' API, you need to register one or multiple endpoints at the proxy. This is currently done by manually adding routes to a config file, but will be done dynamically by service discovery in the future. The registration is a easy task and can be seen best on the [oCIS Hello example](https://owncloud.dev/extensions/ocis_hello/running/#configure-and-start-ocis). -As files in ownCloud must always stay private, unless you share them with your friends or coworkers, requests to oCIS have always a authenticated user context. This user context is also available to your extension and can be used to interact with the users' files. How to get the user context and authentication can be seen on the [oCIS Hello example](https://owncloud.dev/extensions/ocis_hello/settings/#account-uuid). +As files in ownCloud must always stay private, unless you share them with your friends or coworkers, requests to oCIS have an authenticated user context. This user context is also available to your extension and can be used to interact with the users' files. How to get the user context and authentication can be seen on the [oCIS Hello example](https://owncloud.dev/extensions/ocis_hello/settings/#account-uuid). ### Storage @@ -62,15 +62,15 @@ oCIS leverages the CS3 APIs and [CS3 REVA](https://github.com/cs3org/reva) as a If you need to interact with files directly, you have the full power of the [CS3 APIs](https://cs3org.github.io/cs3apis/) in your hand. With the user context and the users' authentication token, which your extensions gets from the proxy, your extension can make these request in behalf of the user. -If your extension needs to store data which is not supposed to life in the users home folder, there is also so called metadata storage which can be used for that purpose without a specific user context. +If your extension needs to store data which is not supposed to live in the user's home folder, there is also a so-called metadata storage which can be used for that purpose without a specific user context. One main point you should get about storage in an oCIS extension is that you should never use the filesystem, but always use the CS3 APIs. ## Development Roadmap -When reading the above section you might have noticed, that some integrations need some manual setup as of now but we are planning to switch to automatic service discovery in a later development stage of oCIS. +Whilst reading the above section you might have noticed that some integrations need a manual setup as of now. As mentioned before, we are planning to switch to automatic service discovery in a later development stage of oCIS. There are some more topics on our roadmap for the extension system: -- Events: allow extensions to register for some events. On occurrence of the event they will receive some kind of notification or a callback. This would for example allow your application to perform actions on the creations, modification or deletion of a file. +- Events: Allow extensions to register for some events. On occurrence of the event, they will then receive some kind of notification or a callback. This would for example allow your application to perform actions on the creation, modification or deletion of a file. - Entitlement of extensions to act in behalf of users without a request context: user should be able to grant and revoke extensions access to their files even in behalf of them eg. in the background. From 27d55882d187399daa916537bada7db6689e1cb5 Mon Sep 17 00:00:00 2001 From: Willy Kloucek <34452982+wkloucek@users.noreply.github.com> Date: Wed, 16 Jun 2021 08:54:26 +0200 Subject: [PATCH 4/9] Apply suggestions from code review Co-authored-by: Pascal Wengerter --- docs/ocis/development/extensions.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/ocis/development/extensions.md b/docs/ocis/development/extensions.md index 5570d843eb..db4f253eb5 100644 --- a/docs/ocis/development/extensions.md +++ b/docs/ocis/development/extensions.md @@ -15,7 +15,7 @@ We will now introduce you to the oCIS extension system and how you can use it fo Technically every service in oCIS is an extension, even if oCIS would not really work without some of them. Therefore, you can draw inspiration from any of the plenty of extensions in the [oCIS monorepo](https://github.com/owncloud/ocis). -Besides these "default" extensions in the oCIS monorepo there are more extensions: +Besides these "default" extensions in the oCIS monorepo, there are two more extensions you should be aware of: - [Hello](https://github.com/owncloud/ocis-hello) - [WOPI server](https://github.com/owncloud/ocis-wopiserver) From fe2ffe1ce4afc135599ad2bb68c959443f2ecc14 Mon Sep 17 00:00:00 2001 From: Willy Kloucek Date: Wed, 16 Jun 2021 09:42:28 +0200 Subject: [PATCH 5/9] be more explainatory about metadata storage --- docs/ocis/development/extensions.md | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/docs/ocis/development/extensions.md b/docs/ocis/development/extensions.md index db4f253eb5..1deea57f17 100644 --- a/docs/ocis/development/extensions.md +++ b/docs/ocis/development/extensions.md @@ -62,9 +62,7 @@ oCIS leverages the CS3 APIs and [CS3 REVA](https://github.com/cs3org/reva) as a If you need to interact with files directly, you have the full power of the [CS3 APIs](https://cs3org.github.io/cs3apis/) in your hand. With the user context and the users' authentication token, which your extensions gets from the proxy, your extension can make these request in behalf of the user. -If your extension needs to store data which is not supposed to live in the user's home folder, there is also a so-called metadata storage which can be used for that purpose without a specific user context. - -One main point you should get about storage in an oCIS extension is that you should never use the filesystem, but always use the CS3 APIs. +If your extension needs to store persistent data which is not supposed to live in the user's home folder, there is also a so-called metadata storage, intended for exactly that purpose. You should always use the metadata storage in favor of the local file system for persistent files, because your extension will then automatically use the storage backend the oCIS admin decides to use. For a temporary cache it is perfectly fine to use the local filesystem. ## Development Roadmap From 5a1d52b1eaf48162af1ba9b926b825e97cbbb1db Mon Sep 17 00:00:00 2001 From: Willy Kloucek Date: Wed, 16 Jun 2021 10:10:14 +0200 Subject: [PATCH 6/9] unify filesystem --- docs/ocis/development/extensions.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/ocis/development/extensions.md b/docs/ocis/development/extensions.md index 1deea57f17..403265dc5a 100644 --- a/docs/ocis/development/extensions.md +++ b/docs/ocis/development/extensions.md @@ -62,7 +62,7 @@ oCIS leverages the CS3 APIs and [CS3 REVA](https://github.com/cs3org/reva) as a If you need to interact with files directly, you have the full power of the [CS3 APIs](https://cs3org.github.io/cs3apis/) in your hand. With the user context and the users' authentication token, which your extensions gets from the proxy, your extension can make these request in behalf of the user. -If your extension needs to store persistent data which is not supposed to live in the user's home folder, there is also a so-called metadata storage, intended for exactly that purpose. You should always use the metadata storage in favor of the local file system for persistent files, because your extension will then automatically use the storage backend the oCIS admin decides to use. For a temporary cache it is perfectly fine to use the local filesystem. +If your extension needs to store persistent data which is not supposed to live in the user's home folder, there is also a so-called metadata storage, intended for exactly that purpose. You should always use the metadata storage in favor of the local filesystem for persistent files, because your extension will then automatically use the storage backend the oCIS admin decides to use. For a temporary cache it is perfectly fine to use the local filesystem. ## Development Roadmap From 78bbd7e4ce947054f28d56cd220f797a649f09d7 Mon Sep 17 00:00:00 2001 From: Willy Kloucek Date: Thu, 17 Jun 2021 08:36:17 +0200 Subject: [PATCH 7/9] remove development roadmap --- docs/ocis/development/extensions.md | 9 --------- 1 file changed, 9 deletions(-) diff --git a/docs/ocis/development/extensions.md b/docs/ocis/development/extensions.md index 403265dc5a..f0ff91dc59 100644 --- a/docs/ocis/development/extensions.md +++ b/docs/ocis/development/extensions.md @@ -63,12 +63,3 @@ oCIS leverages the CS3 APIs and [CS3 REVA](https://github.com/cs3org/reva) as a If you need to interact with files directly, you have the full power of the [CS3 APIs](https://cs3org.github.io/cs3apis/) in your hand. With the user context and the users' authentication token, which your extensions gets from the proxy, your extension can make these request in behalf of the user. If your extension needs to store persistent data which is not supposed to live in the user's home folder, there is also a so-called metadata storage, intended for exactly that purpose. You should always use the metadata storage in favor of the local filesystem for persistent files, because your extension will then automatically use the storage backend the oCIS admin decides to use. For a temporary cache it is perfectly fine to use the local filesystem. - -## Development Roadmap - -Whilst reading the above section you might have noticed that some integrations need a manual setup as of now. As mentioned before, we are planning to switch to automatic service discovery in a later development stage of oCIS. - -There are some more topics on our roadmap for the extension system: - -- Events: Allow extensions to register for some events. On occurrence of the event, they will then receive some kind of notification or a callback. This would for example allow your application to perform actions on the creation, modification or deletion of a file. -- Entitlement of extensions to act in behalf of users without a request context: user should be able to grant and revoke extensions access to their files even in behalf of them eg. in the background. From a8a6bb62309f151c10867d577d180cc082e94830 Mon Sep 17 00:00:00 2001 From: Willy Kloucek <34452982+wkloucek@users.noreply.github.com> Date: Mon, 21 Jun 2021 09:37:57 +0200 Subject: [PATCH 8/9] Apply suggestions from code review Co-authored-by: Pascal Wengerter --- docs/ocis/development/extensions.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/ocis/development/extensions.md b/docs/ocis/development/extensions.md index f0ff91dc59..1605202a8d 100644 --- a/docs/ocis/development/extensions.md +++ b/docs/ocis/development/extensions.md @@ -7,9 +7,9 @@ geekdocEditPath: edit/master/docs/ocis/development geekdocFilePath: extensions.md --- -oCIS is all about files, sync and share - but most of the time there is more you want to do with your files, e.g. having a different view on your photo collection or editing your offices files in an online file editor. ownCloud 10 faced the same problem and solved them with applications, which can extend the functionality of ownCloud 10 in a wide range. oCIS has a similar concept to be extended in its functionality: Extensions. Because oCIS is different in its architecture compared to ownCloud 10, this also applies to the extensions. An extension is basically any running code which integrates into oCIS and provides functionality to oCIS and its users. Because extensions are just microservices providing an API, you can technically choose any programming language you like - a huge improvement to ownCloud 10, where it was nearly impossible to use a different programming language than PHP. +oCIS is all about files, sync and share - but most of the time there is more you want to do with your files, e.g. having a different view on your photo collection or editing your offices files in an online file editor. ownCloud 10 faced the same problem and solved it with `applications`, which can extend the functionality of ownCloud 10 in a wide range. Since oCIS is different in its architecture compared to ownCloud 10, we had to come up with a similiar (yet slightly different) solution. To extend the functionality of oCIS, you can write or install `extensions`. An extension is basically any running code which integrates into oCIS and provides functionality to oCIS and its users. Because extensions are just microservices providing an API, you can technically choose any programming language you like - a huge improvement to ownCloud 10, where it was nearly impossible to use a different programming language than PHP. -We will now introduce you to the oCIS extension system and how you can use it for your extension. +We will now introduce you to the oCIS extension system and show you how you can create a custom extension yourself. ## Extension examples @@ -52,14 +52,14 @@ An extension likely has some behaviour which the user can configure. Fundamental The Proxy is an API gateway and acts as the single connection point where all external request from users and devices need to pass through. -To make sure that requests can reach your extensions' API, you need to register one or multiple endpoints at the proxy. This is currently done by manually adding routes to a config file, but will be done dynamically by service discovery in the future. The registration is a easy task and can be seen best on the [oCIS Hello example](https://owncloud.dev/extensions/ocis_hello/running/#configure-and-start-ocis). +To make sure that requests can reach your extension's API, you need to register one or multiple endpoints at the proxy. This is currently done by manually adding routes to a config file, but will be done dynamically by service discovery in the future. The registration is a easy task and can be seen best on the [oCIS Hello example](https://owncloud.dev/extensions/ocis_hello/running/#configure-and-start-ocis). -As files in ownCloud must always stay private, unless you share them with your friends or coworkers, requests to oCIS have an authenticated user context. This user context is also available to your extension and can be used to interact with the users' files. How to get the user context and authentication can be seen on the [oCIS Hello example](https://owncloud.dev/extensions/ocis_hello/settings/#account-uuid). +As files in ownCloud must always stay private (unless you share them with your friends or coworkers), requests to oCIS have an authenticated user context. This user context is also available to your extension and can be used to interact with the user's files. How to get the user context and authentication can be seen on the [oCIS Hello example](https://owncloud.dev/extensions/ocis_hello/settings/#account-uuid). ### Storage oCIS leverages the CS3 APIs and [CS3 REVA](https://github.com/cs3org/reva) as a storage system because it offers a very flexible setup and supports a variety of storage backends like EOS, S3 and of course your local hard drive. REVA makes it easy to support more storage backends as needed. -If you need to interact with files directly, you have the full power of the [CS3 APIs](https://cs3org.github.io/cs3apis/) in your hand. With the user context and the users' authentication token, which your extensions gets from the proxy, your extension can make these request in behalf of the user. +If you need to interact with files directly, you have the full power of the [CS3 APIs](https://cs3org.github.io/cs3apis/) in your hand. With the user context and the user's authentication token, which your extensions gets from the proxy, your extension can make these request in behalf of the user. If your extension needs to store persistent data which is not supposed to live in the user's home folder, there is also a so-called metadata storage, intended for exactly that purpose. You should always use the metadata storage in favor of the local filesystem for persistent files, because your extension will then automatically use the storage backend the oCIS admin decides to use. For a temporary cache it is perfectly fine to use the local filesystem. From a3007e515aa45ae5bd5440dadafcaf2de0affd12 Mon Sep 17 00:00:00 2001 From: Willy Kloucek Date: Mon, 21 Jun 2021 09:39:14 +0200 Subject: [PATCH 9/9] remove references to future --- docs/ocis/development/extensions.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/ocis/development/extensions.md b/docs/ocis/development/extensions.md index 1605202a8d..e8fbbbb169 100644 --- a/docs/ocis/development/extensions.md +++ b/docs/ocis/development/extensions.md @@ -40,7 +40,7 @@ If your extension is not just doing something in the background, you will need a ownCloud Web allows you to write an extension for itself and therefore offers a seamless user experience. Upon login, the user will be able to use the application switcher to switch between the files view, settings and other available and installed extensions, yours included. Furthermore it is also possible to register your extension for different file actions. As an example, you could offer your extension to the user for creating and editing office documents. The user will then be able to create or open a file with your application directly from the files view. How to provide create an extension for ownCloud Web can be seen best in [the Hello extension](https://github.com/owncloud/ocis-hello/blob/master/ui/app.js), whereas plain file handling without any web frontend is available in the [WOPI server extension](https://github.com/owncloud/ocis-wopiserver/blob/master/ui/app.js). -To make ownCloud Web pick up your extension, you need to activate it in the configuration like seen in the [Hello extension](https://owncloud.dev/extensions/ocis_hello/running/#configure-and-start-ocis). As of now this is a manual task, but in the future this will be done automatically by service discovery. +To make ownCloud Web pick up your extension, you need to activate it in the configuration like seen in the [Hello extension](https://owncloud.dev/extensions/ocis_hello/running/#configure-and-start-ocis). For a consistent look and feel, ownCloud Web uses a external design library, the [ownCloud design system](https://github.com/owncloud/owncloud-design-system). Since its classes and components are available through the wrapping `web runtime`, we highly recommend you to leverage it in your extension as well. @@ -52,7 +52,7 @@ An extension likely has some behaviour which the user can configure. Fundamental The Proxy is an API gateway and acts as the single connection point where all external request from users and devices need to pass through. -To make sure that requests can reach your extension's API, you need to register one or multiple endpoints at the proxy. This is currently done by manually adding routes to a config file, but will be done dynamically by service discovery in the future. The registration is a easy task and can be seen best on the [oCIS Hello example](https://owncloud.dev/extensions/ocis_hello/running/#configure-and-start-ocis). +To make sure that requests can reach your extension's API, you need to register one or multiple endpoints at the proxy. The registration is a easy task and can be seen best on the [oCIS Hello example](https://owncloud.dev/extensions/ocis_hello/running/#configure-and-start-ocis). As files in ownCloud must always stay private (unless you share them with your friends or coworkers), requests to oCIS have an authenticated user context. This user context is also available to your extension and can be used to interact with the user's files. How to get the user context and authentication can be seen on the [oCIS Hello example](https://owncloud.dev/extensions/ocis_hello/settings/#account-uuid).