You are viewing a plain text version of this content. The canonical link for it is here.
Posted to issues@openwhisk.apache.org by GitBox <gi...@apache.org> on 2020/03/05 17:52:25 UTC
[GitHub] [openwhisk] pwplusnick opened a new pull request #4850: Add single
entrypoint proxy interface documentation
pwplusnick opened a new pull request #4850: Add single entrypoint proxy interface documentation
URL: https://github.com/apache/openwhisk/pull/4850
## Description
Several implementations of this proxy contract exist for multiple
different runtimes. In effort to document this existing code, these
changes have been put down as part of the documentation for OpenWhisk
since they do not properly fit under the definition of any one runtime.
In addition, a small footer has been added to the docs/action-new.md to
make note of and link to the docs/single_entrypoint_proxy_contract.md describing
and giving examples of this contract.
<!--- Provide a concise summary of your changes in the Title -->
<!--- Provide a detailed description of your changes. -->
<!--- Include details of what problem you are solving and how your changes are tested. -->
## Related issue and scope
<!--- Please include a link to a related issue if there is one. -->
n/a
## My changes affect the following components
<!--- Select below all system components are affected by your change. -->
<!--- Enter an `x` in all applicable boxes. -->
- [ ] API
- [ ] Controller
- [ ] Message Bus (e.g., Kafka)
- [ ] Loadbalancer
- [ ] Invoker
- [ ] Intrinsic actions (e.g., sequences, conductors)
- [ ] Data stores (e.g., CouchDB)
- [ ] Tests
- [ ] Deployment
- [ ] CLI
- [ ] General tooling
- [x ] Documentation
## Types of changes
<!--- What types of changes does your code introduce? Use `x` in all the boxes that apply: -->
- [ ] Bug fix (generally a non-breaking change which closes an issue).
- [x] Enhancement or new feature (adds new functionality).
- [ ] Breaking change (a bug fix or enhancement which changes existing behavior).
## Checklist:
<!--- Please review the points below which help you make sure you've covered all aspects of the change you're making. -->
- [x ] I signed an [Apache CLA](https://github.com/apache/openwhisk/blob/master/CONTRIBUTING.md).
- [x ] I reviewed the [style guides](https://github.com/apache/openwhisk/wiki/Contributing:-Git-guidelines#code-readiness) and followed the recommendations (Travis CI will check :).
- [ ] I added tests to cover my changes.
- [ ] My changes require further changes to the documentation.
- [x ] I updated the documentation where necessary.
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
With regards,
Apache Git Services
[GitHub] [openwhisk] mrutkows merged pull request #4850: Add single
entrypoint proxy interface documentation
Posted by GitBox <gi...@apache.org>.
mrutkows merged pull request #4850: Add single entrypoint proxy interface documentation
URL: https://github.com/apache/openwhisk/pull/4850
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
With regards,
Apache Git Services
[GitHub] [openwhisk] pwplusnick edited a comment on issue #4850: Add single
entrypoint proxy interface documentation
Posted by GitBox <gi...@apache.org>.
pwplusnick edited a comment on issue #4850: Add single entrypoint proxy interface documentation
URL: https://github.com/apache/openwhisk/pull/4850#issuecomment-595504661
~https://github.com/apache/openwhisk/pull/4850/commits/31df9a6e13a6fbbf0530e944b804d8abc8a3bb97
Note this is the version you should look at for file changes. The last few commits were just me trying to get a markdown table working, but it doesn't look like it will pan out.~ The version presented is now up to date
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
With regards,
Apache Git Services
[GitHub] [openwhisk] mrutkows commented on issue #4850: Add single
entrypoint proxy interface documentation
Posted by GitBox <gi...@apache.org>.
mrutkows commented on issue #4850: Add single entrypoint proxy interface documentation
URL: https://github.com/apache/openwhisk/pull/4850#issuecomment-597153364
@pwplusnick Will, you may want to circle back with Michele and team to invite them to make follow-on changes as it seems they may have been too busy in the last week to review this specific docs. PR.
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
With regards,
Apache Git Services
[GitHub] [openwhisk] pwplusnick commented on a change in pull request #4850:
Add single entrypoint proxy interface documentation
Posted by GitBox <gi...@apache.org>.
pwplusnick commented on a change in pull request #4850: Add single entrypoint proxy interface documentation
URL: https://github.com/apache/openwhisk/pull/4850#discussion_r388632892
##########
File path: docs/single_entrypoint_proxy_contract.md
##########
@@ -0,0 +1,362 @@
+# Action Proxy Single Entrypoint Interface
+
+The typical endpoints used by the OpenWhisk control plane are not used in single entrypoint execution environments such as Knative. Initialization and running are still essential to how OpenWhisk runtimes function, but they are done in a different methodology than `/init` and `/run` endpoints. The proxy that shapes how the calls are preprocessed and postprocessed to emulate some of the functionality provided by the OpenWhisk control plane. In single entrypoint supported runtime proxy implementations, both initailization and running are done via the `/` root endpoint. The sections below explain the interface the runtime proxy must adhere to initialize and run via a single entrypoint execution environment.
+
+## Init
+
+To initialize an undifferintiated stem cell, the interface is to pass a JSON object containing the key `init` to the `/` endpoint. The value corresponding to the `init` key is the same JSON object as the [initialization of standard OpenWhisk actions](actions-new.md#initialization). For example:
+```json
+{
+ "init": {
+ "name" : "hello",
+ "main" : "main",
+ "code" : "function main(params) {return { payload: 'Hello ' + params.name + ' from ' + params.place + '!' };}",
+ "binary": false,
+ "env": {}
+ }
+}
+```
+Just as with the OpenWhisk control plane, specialized function containers need no explicit initialization.
+
+## Run
+
+To run an action, the interface is to pass a JSON object containing the key `activation` to the `/` endpoint. The value corresponding to the `activation` key is largely the same JSON object as the [activation of standard OpenWhisk actions](actions-new.md#activation). The key difference is that `value` is not used under the `activation` key to pass parameters to the underlying function. To see the interface for passing keys to the underlying functions see section below.
+Example of an activation:
+```json
+{
+ "activation": {
+ "namespace": "",
+ "action_name": "hello",
+ "api_host": "",
+ "api_key": "",
+ "activation_id": "",
+ "transaction_id": "",
+ "deadline": 1000000
+ },
+ "value": {
+ "name": "Alan Turing",
+ "place": "England"
+ }
+}
+```
+One thing to note is when these values are present outside of the context of the OpenWhisk control plane, they may not actually be used for anything. However, the `activation` key is still necessary to signal the intent to run the function.
+
+## Passing parameters
+
+Similar to the description of the `value` key in the `activation` object during the [activation of standard OpenWhisk actions](actions-new.md#activation), a top level `value` key in the JSON object passed to the `/` endpoint (with a corresponding top level `activation` key) is how parameters are passed to the underlying function being run.
+In the following example:
+```json
+{
+ "activation": {
+ "namespace": "",
+ "action_name": "hello",
+ "api_host": "",
+ "api_key": "",
+ "activation_id": "",
+ "transaction_id": "",
+ "deadline": 1000000
+ },
+ "value": {
+ "name": "Alan Turing",
+ "location": "England"
+ }
+}
+```
+
+The underlying function would recieve a parameters map with the keys `name` and `location` with the values `Alan Turing` and `England` respectively.
+
+## Init/Run
+
+OpenWhisk stem cell runtimes being executed in a single entrypoint execution environment can be both initialized and activated at the same time by passing both `init` and `activation` keys in the same JSON object to the `/` endpoint. This will first initialize the runtime, following the same procedures described above, and then subsequently activate the same runtime.
+For example:
+```json
+{
+ "init": {
+ "name" : "hello",
+ "main" : "main",
+ "code" : "function main(params) {return { payload: 'Hello ' + params.name + ' from ' + params.place + '!' };}",
+ "binary": false,
+ "env": {}
+ },
+ "activation": {
+ "namespace": "",
+ "action_name": "hello",
+ "api_host": "",
+ "api_key": "",
+ "activation_id": "",
+ "transaction_id": "",
+ "deadline": 1000000
+ },
+ "value": {
+ "name": "Alan Turing",
+ "location": "England"
+ }
+}
+```
+The above JSON object would instruct the runtime to be initialized with the function under `init.code` and be run with the function being passed the object `{name: "Alan Turing", location: "England"}`. It would then return the JSON object
+```json
+{
+ "payload": "Hello Alan Turing from England!"
+}
+```
+
+## Example Cases
+Below is a table outlining the standardized behaviors that any action proxy implementation needs to fulfill. NodeJS was the sample language used, but corresponding example cases could be written in the language of the corresponding runtime it is showcasing.
+
+
+<table border="2" cellspacing="0" cellpadding="6" rules="groups" frame="hsides">
Review comment:
There is no way to do that without losing the formatting unfortunately. I'll leave the last few commits up for a little while so you can see for yourself. Because there is no way to do a multi-line cell in markdown tables directly, so you lose the ability to control the width of the cell which breaks the code formatting.
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
With regards,
Apache Git Services
[GitHub] [openwhisk] mrutkows commented on a change in pull request #4850:
Add single entrypoint proxy interface documentation
Posted by GitBox <gi...@apache.org>.
mrutkows commented on a change in pull request #4850: Add single entrypoint proxy interface documentation
URL: https://github.com/apache/openwhisk/pull/4850#discussion_r389894341
##########
File path: docs/actions-new.md
##########
@@ -282,3 +282,8 @@ other OpenWhisk clients. In which case, appropriate tests should be added as nec
The OpenWhisk platform will perform a generic integration test as part of its basic
system tests. This integration test will require a [test function](#the-test-action) to
be available so that the test harness can create, invoke, and delete the action.
+
+### Additonal Execution Environments
Review comment:
Please add "Supporting:" to the title and perhaps setup the next section a bit... look at taking the first sentence or two from the next section. Then allow the next section to pickup the "single entrypoint" narrative with knative as the first historical example.
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
With regards,
Apache Git Services
[GitHub] [openwhisk] rabbah commented on a change in pull request #4850: Add
single entrypoint proxy interface documentation
Posted by GitBox <gi...@apache.org>.
rabbah commented on a change in pull request #4850: Add single entrypoint proxy interface documentation
URL: https://github.com/apache/openwhisk/pull/4850#discussion_r388507692
##########
File path: docs/single_entrypoint_proxy_contract.md
##########
@@ -0,0 +1,362 @@
+# Action Proxy Single Entrypoint Interface
+
+The typical endpoints used by the OpenWhisk control plane are not used in single entrypoint execution environments such as Knative. Initialization and running are still essential to how OpenWhisk runtimes function, but they are done in a different methodology than `/init` and `/run` endpoints. The proxy that shapes how the calls are preprocessed and postprocessed to emulate some of the functionality provided by the OpenWhisk control plane. In single entrypoint supported runtime proxy implementations, both initailization and running are done via the `/` root endpoint. The sections below explain the interface the runtime proxy must adhere to initialize and run via a single entrypoint execution environment.
+
+## Init
+
+To initialize an undifferintiated stem cell, the interface is to pass a JSON object containing the key `init` to the `/` endpoint. The value corresponding to the `init` key is the same JSON object as the [initialization of standard OpenWhisk actions](actions-new.md#initialization). For example:
+```json
+{
+ "init": {
+ "name" : "hello",
+ "main" : "main",
+ "code" : "function main(params) {return { payload: 'Hello ' + params.name + ' from ' + params.place + '!' };}",
+ "binary": false,
+ "env": {}
+ }
+}
+```
+Just as with the OpenWhisk control plane, specialized function containers need no explicit initialization.
+
+## Run
+
+To run an action, the interface is to pass a JSON object containing the key `activation` to the `/` endpoint. The value corresponding to the `activation` key is largely the same JSON object as the [activation of standard OpenWhisk actions](actions-new.md#activation). The key difference is that `value` is not used under the `activation` key to pass parameters to the underlying function. To see the interface for passing keys to the underlying functions see section below.
+Example of an activation:
+```json
+{
+ "activation": {
+ "namespace": "",
+ "action_name": "hello",
+ "api_host": "",
+ "api_key": "",
+ "activation_id": "",
+ "transaction_id": "",
+ "deadline": 1000000
+ },
+ "value": {
+ "name": "Alan Turing",
+ "place": "England"
+ }
+}
+```
+One thing to note is when these values are present outside of the context of the OpenWhisk control plane, they may not actually be used for anything. However, the `activation` key is still necessary to signal the intent to run the function.
+
+## Passing parameters
+
+Similar to the description of the `value` key in the `activation` object during the [activation of standard OpenWhisk actions](actions-new.md#activation), a top level `value` key in the JSON object passed to the `/` endpoint (with a corresponding top level `activation` key) is how parameters are passed to the underlying function being run.
+In the following example:
+```json
+{
+ "activation": {
+ "namespace": "",
+ "action_name": "hello",
+ "api_host": "",
+ "api_key": "",
+ "activation_id": "",
+ "transaction_id": "",
+ "deadline": 1000000
+ },
+ "value": {
+ "name": "Alan Turing",
+ "location": "England"
+ }
+}
+```
+
+The underlying function would recieve a parameters map with the keys `name` and `location` with the values `Alan Turing` and `England` respectively.
+
+## Init/Run
+
+OpenWhisk stem cell runtimes being executed in a single entrypoint execution environment can be both initialized and activated at the same time by passing both `init` and `activation` keys in the same JSON object to the `/` endpoint. This will first initialize the runtime, following the same procedures described above, and then subsequently activate the same runtime.
+For example:
+```json
+{
+ "init": {
+ "name" : "hello",
+ "main" : "main",
+ "code" : "function main(params) {return { payload: 'Hello ' + params.name + ' from ' + params.place + '!' };}",
+ "binary": false,
+ "env": {}
+ },
+ "activation": {
+ "namespace": "",
+ "action_name": "hello",
+ "api_host": "",
+ "api_key": "",
+ "activation_id": "",
+ "transaction_id": "",
+ "deadline": 1000000
+ },
+ "value": {
+ "name": "Alan Turing",
+ "location": "England"
+ }
+}
+```
+The above JSON object would instruct the runtime to be initialized with the function under `init.code` and be run with the function being passed the object `{name: "Alan Turing", location: "England"}`. It would then return the JSON object
+```json
+{
+ "payload": "Hello Alan Turing from England!"
+}
+```
+
+## Example Cases
+Below is a table outlining the standardized behaviors that any action proxy implementation needs to fulfill. NodeJS was the sample language used, but corresponding example cases could be written in the language of the corresponding runtime it is showcasing.
+
+
+<table border="2" cellspacing="0" cellpadding="6" rules="groups" frame="hsides">
Review comment:
can you use a markdown table instead?
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
With regards,
Apache Git Services
[GitHub] [openwhisk] rabbah commented on issue #4850: Add single entrypoint
proxy interface documentation
Posted by GitBox <gi...@apache.org>.
rabbah commented on issue #4850: Add single entrypoint proxy interface documentation
URL: https://github.com/apache/openwhisk/pull/4850#issuecomment-595624498
Thanks for considering it and trying.
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
With regards,
Apache Git Services
[GitHub] [openwhisk] codecov-io commented on issue #4850: Add single
entrypoint proxy interface documentation
Posted by GitBox <gi...@apache.org>.
codecov-io commented on issue #4850: Add single entrypoint proxy interface documentation
URL: https://github.com/apache/openwhisk/pull/4850#issuecomment-596022442
# [Codecov](https://codecov.io/gh/apache/openwhisk/pull/4850?src=pr&el=h1) Report
> Merging [#4850](https://codecov.io/gh/apache/openwhisk/pull/4850?src=pr&el=desc) into [master](https://codecov.io/gh/apache/openwhisk/commit/dab68ece3e24a426a844ccdb992c176b9d06b8fa?src=pr&el=desc) will **decrease** coverage by `45.75%`.
> The diff coverage is `n/a`.
[](https://codecov.io/gh/apache/openwhisk/pull/4850?src=pr&el=tree)
```diff
@@ Coverage Diff @@
## master #4850 +/- ##
===========================================
- Coverage 81.66% 35.91% -45.76%
===========================================
Files 197 199 +2
Lines 9016 9169 +153
Branches 372 374 +2
===========================================
- Hits 7363 3293 -4070
- Misses 1653 5876 +4223
```
| [Impacted Files](https://codecov.io/gh/apache/openwhisk/pull/4850?src=pr&el=tree) | Coverage Δ | |
|---|---|---|
| [...openwhisk/core/entitlement/PackageCollection.scala](https://codecov.io/gh/apache/openwhisk/pull/4850/diff?src=pr&el=tree#diff-Y29yZS9jb250cm9sbGVyL3NyYy9tYWluL3NjYWxhL29yZy9hcGFjaGUvb3BlbndoaXNrL2NvcmUvZW50aXRsZW1lbnQvUGFja2FnZUNvbGxlY3Rpb24uc2NhbGE=) | `0% <0%> (-100%)` | :arrow_down: |
| [...pache/openwhisk/core/controller/CorsSettings.scala](https://codecov.io/gh/apache/openwhisk/pull/4850/diff?src=pr&el=tree#diff-Y29yZS9jb250cm9sbGVyL3NyYy9tYWluL3NjYWxhL29yZy9hcGFjaGUvb3BlbndoaXNrL2NvcmUvY29udHJvbGxlci9Db3JzU2V0dGluZ3Muc2NhbGE=) | `0% <0%> (-100%)` | :arrow_down: |
| [...core/database/cosmosdb/RxObservableImplicits.scala](https://codecov.io/gh/apache/openwhisk/pull/4850/diff?src=pr&el=tree#diff-Y29tbW9uL3NjYWxhL3NyYy9tYWluL3NjYWxhL29yZy9hcGFjaGUvb3BlbndoaXNrL2NvcmUvZGF0YWJhc2UvY29zbW9zZGIvUnhPYnNlcnZhYmxlSW1wbGljaXRzLnNjYWxh) | `0% <0%> (-100%)` | :arrow_down: |
| [...ore/containerpool/kubernetes/WhiskPodBuilder.scala](https://codecov.io/gh/apache/openwhisk/pull/4850/diff?src=pr&el=tree#diff-Y29yZS9pbnZva2VyL3NyYy9tYWluL3NjYWxhL29yZy9hcGFjaGUvb3BlbndoaXNrL2NvcmUvY29udGFpbmVycG9vbC9rdWJlcm5ldGVzL1doaXNrUG9kQnVpbGRlci5zY2FsYQ==) | `0% <0%> (-100%)` | :arrow_down: |
| [...he/openwhisk/core/entitlement/KindRestrictor.scala](https://codecov.io/gh/apache/openwhisk/pull/4850/diff?src=pr&el=tree#diff-Y29yZS9jb250cm9sbGVyL3NyYy9tYWluL3NjYWxhL29yZy9hcGFjaGUvb3BlbndoaXNrL2NvcmUvZW50aXRsZW1lbnQvS2luZFJlc3RyaWN0b3Iuc2NhbGE=) | `0% <0%> (-100%)` | :arrow_down: |
| [...nwhisk/core/database/cosmosdb/CosmosDBConfig.scala](https://codecov.io/gh/apache/openwhisk/pull/4850/diff?src=pr&el=tree#diff-Y29tbW9uL3NjYWxhL3NyYy9tYWluL3NjYWxhL29yZy9hcGFjaGUvb3BlbndoaXNrL2NvcmUvZGF0YWJhc2UvY29zbW9zZGIvQ29zbW9zREJDb25maWcuc2NhbGE=) | `0% <0%> (-100%)` | :arrow_down: |
| [...enwhisk/connector/kafka/KamonMetricsReporter.scala](https://codecov.io/gh/apache/openwhisk/pull/4850/diff?src=pr&el=tree#diff-Y29tbW9uL3NjYWxhL3NyYy9tYWluL3NjYWxhL29yZy9hcGFjaGUvb3BlbndoaXNrL2Nvbm5lY3Rvci9rYWZrYS9LYW1vbk1ldHJpY3NSZXBvcnRlci5zY2FsYQ==) | `0% <0%> (-100%)` | :arrow_down: |
| [...hisk/core/database/cosmosdb/ReferenceCounted.scala](https://codecov.io/gh/apache/openwhisk/pull/4850/diff?src=pr&el=tree#diff-Y29tbW9uL3NjYWxhL3NyYy9tYWluL3NjYWxhL29yZy9hcGFjaGUvb3BlbndoaXNrL2NvcmUvZGF0YWJhc2UvY29zbW9zZGIvUmVmZXJlbmNlQ291bnRlZC5zY2FsYQ==) | `0% <0%> (-100%)` | :arrow_down: |
| [...e/database/cosmosdb/cache/ChangeFeedConsumer.scala](https://codecov.io/gh/apache/openwhisk/pull/4850/diff?src=pr&el=tree#diff-Y29yZS9jb3Ntb3NkYi9jYWNoZS1pbnZhbGlkYXRvci9zcmMvbWFpbi9zY2FsYS9vcmcvYXBhY2hlL29wZW53aGlzay9jb3JlL2RhdGFiYXNlL2Nvc21vc2RiL2NhY2hlL0NoYW5nZUZlZWRDb25zdW1lci5zY2FsYQ==) | `0% <0%> (-100%)` | :arrow_down: |
| [...core/controller/actions/PostActionActivation.scala](https://codecov.io/gh/apache/openwhisk/pull/4850/diff?src=pr&el=tree#diff-Y29yZS9jb250cm9sbGVyL3NyYy9tYWluL3NjYWxhL29yZy9hcGFjaGUvb3BlbndoaXNrL2NvcmUvY29udHJvbGxlci9hY3Rpb25zL1Bvc3RBY3Rpb25BY3RpdmF0aW9uLnNjYWxh) | `0% <0%> (-100%)` | :arrow_down: |
| ... and [136 more](https://codecov.io/gh/apache/openwhisk/pull/4850/diff?src=pr&el=tree-more) | |
------
[Continue to review full report at Codecov](https://codecov.io/gh/apache/openwhisk/pull/4850?src=pr&el=continue).
> **Legend** - [Click here to learn more](https://docs.codecov.io/docs/codecov-delta)
> `Δ = absolute <relative> (impact)`, `ø = not affected`, `? = missing data`
> Powered by [Codecov](https://codecov.io/gh/apache/openwhisk/pull/4850?src=pr&el=footer). Last update [dab68ec...26cd468](https://codecov.io/gh/apache/openwhisk/pull/4850?src=pr&el=lastupdated). Read the [comment docs](https://docs.codecov.io/docs/pull-request-comments).
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
With regards,
Apache Git Services
[GitHub] [openwhisk] pwplusnick commented on a change in pull request #4850:
Add single entrypoint proxy interface documentation
Posted by GitBox <gi...@apache.org>.
pwplusnick commented on a change in pull request #4850: Add single entrypoint proxy interface documentation
URL: https://github.com/apache/openwhisk/pull/4850#discussion_r388632892
##########
File path: docs/single_entrypoint_proxy_contract.md
##########
@@ -0,0 +1,362 @@
+# Action Proxy Single Entrypoint Interface
+
+The typical endpoints used by the OpenWhisk control plane are not used in single entrypoint execution environments such as Knative. Initialization and running are still essential to how OpenWhisk runtimes function, but they are done in a different methodology than `/init` and `/run` endpoints. The proxy that shapes how the calls are preprocessed and postprocessed to emulate some of the functionality provided by the OpenWhisk control plane. In single entrypoint supported runtime proxy implementations, both initailization and running are done via the `/` root endpoint. The sections below explain the interface the runtime proxy must adhere to initialize and run via a single entrypoint execution environment.
+
+## Init
+
+To initialize an undifferintiated stem cell, the interface is to pass a JSON object containing the key `init` to the `/` endpoint. The value corresponding to the `init` key is the same JSON object as the [initialization of standard OpenWhisk actions](actions-new.md#initialization). For example:
+```json
+{
+ "init": {
+ "name" : "hello",
+ "main" : "main",
+ "code" : "function main(params) {return { payload: 'Hello ' + params.name + ' from ' + params.place + '!' };}",
+ "binary": false,
+ "env": {}
+ }
+}
+```
+Just as with the OpenWhisk control plane, specialized function containers need no explicit initialization.
+
+## Run
+
+To run an action, the interface is to pass a JSON object containing the key `activation` to the `/` endpoint. The value corresponding to the `activation` key is largely the same JSON object as the [activation of standard OpenWhisk actions](actions-new.md#activation). The key difference is that `value` is not used under the `activation` key to pass parameters to the underlying function. To see the interface for passing keys to the underlying functions see section below.
+Example of an activation:
+```json
+{
+ "activation": {
+ "namespace": "",
+ "action_name": "hello",
+ "api_host": "",
+ "api_key": "",
+ "activation_id": "",
+ "transaction_id": "",
+ "deadline": 1000000
+ },
+ "value": {
+ "name": "Alan Turing",
+ "place": "England"
+ }
+}
+```
+One thing to note is when these values are present outside of the context of the OpenWhisk control plane, they may not actually be used for anything. However, the `activation` key is still necessary to signal the intent to run the function.
+
+## Passing parameters
+
+Similar to the description of the `value` key in the `activation` object during the [activation of standard OpenWhisk actions](actions-new.md#activation), a top level `value` key in the JSON object passed to the `/` endpoint (with a corresponding top level `activation` key) is how parameters are passed to the underlying function being run.
+In the following example:
+```json
+{
+ "activation": {
+ "namespace": "",
+ "action_name": "hello",
+ "api_host": "",
+ "api_key": "",
+ "activation_id": "",
+ "transaction_id": "",
+ "deadline": 1000000
+ },
+ "value": {
+ "name": "Alan Turing",
+ "location": "England"
+ }
+}
+```
+
+The underlying function would recieve a parameters map with the keys `name` and `location` with the values `Alan Turing` and `England` respectively.
+
+## Init/Run
+
+OpenWhisk stem cell runtimes being executed in a single entrypoint execution environment can be both initialized and activated at the same time by passing both `init` and `activation` keys in the same JSON object to the `/` endpoint. This will first initialize the runtime, following the same procedures described above, and then subsequently activate the same runtime.
+For example:
+```json
+{
+ "init": {
+ "name" : "hello",
+ "main" : "main",
+ "code" : "function main(params) {return { payload: 'Hello ' + params.name + ' from ' + params.place + '!' };}",
+ "binary": false,
+ "env": {}
+ },
+ "activation": {
+ "namespace": "",
+ "action_name": "hello",
+ "api_host": "",
+ "api_key": "",
+ "activation_id": "",
+ "transaction_id": "",
+ "deadline": 1000000
+ },
+ "value": {
+ "name": "Alan Turing",
+ "location": "England"
+ }
+}
+```
+The above JSON object would instruct the runtime to be initialized with the function under `init.code` and be run with the function being passed the object `{name: "Alan Turing", location: "England"}`. It would then return the JSON object
+```json
+{
+ "payload": "Hello Alan Turing from England!"
+}
+```
+
+## Example Cases
+Below is a table outlining the standardized behaviors that any action proxy implementation needs to fulfill. NodeJS was the sample language used, but corresponding example cases could be written in the language of the corresponding runtime it is showcasing.
+
+
+<table border="2" cellspacing="0" cellpadding="6" rules="groups" frame="hsides">
Review comment:
There is no way to do that without losing the formatting unfortunately. I'll leave the last few commits up for a little while so you can see for yourself. Because there is no way to do a multi-line cell in markdown tables directly, you lose the ability to control the width of the cell which breaks the code formatting.
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
With regards,
Apache Git Services
[GitHub] [openwhisk] pwplusnick commented on a change in pull request #4850:
Add single entrypoint proxy interface documentation
Posted by GitBox <gi...@apache.org>.
pwplusnick commented on a change in pull request #4850: Add single entrypoint proxy interface documentation
URL: https://github.com/apache/openwhisk/pull/4850#discussion_r389901917
##########
File path: docs/single_entrypoint_proxy_contract.md
##########
@@ -0,0 +1,383 @@
+<!--
+#
+# Licensed to the Apache Software Foundation (ASF) under one or more
+# contributor license agreements. See the NOTICE file distributed with
+# this work for additional information regarding copyright ownership.
+# The ASF licenses this file to You under the Apache License, Version 2.0
+# (the "License"); you may not use this file except in compliance with
+# the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+-->
+# Action Proxy Single Entrypoint Interface
+
+The typical endpoints used by the OpenWhisk control plane are not used in single entrypoint execution environments such as Knative. Initialization and running are still essential to how OpenWhisk runtimes function, but they are done in a different methodology than `/init` and `/run` endpoints. The proxy that shapes how the calls are preprocessed and postprocessed to emulate some of the functionality provided by the OpenWhisk control plane. In single entrypoint supported runtime proxy implementations, both initailization and running are done via the `/` root endpoint. The sections below explain the interface the runtime proxy must adhere to initialize and run via a single entrypoint execution environment.
+
+## Init
+
+To initialize an undifferintiated stem cell, the interface is to pass a JSON object containing the key `init` to the `/` endpoint. The value corresponding to the `init` key is the same JSON object as the [initialization of standard OpenWhisk actions](actions-new.md#initialization). For example:
+```json
+{
+ "init": {
+ "name" : "hello",
+ "main" : "main",
+ "code" : "function main(params) {return { payload: 'Hello ' + params.name + ' from ' + params.place + '!' };}",
+ "binary": false,
+ "env": {}
+ }
+}
+```
+Just as with the OpenWhisk control plane, specialized function containers need no explicit initialization.
+
+## Run
+
+To run an action, the interface is to pass a JSON object containing the key `activation` to the `/` endpoint. The value corresponding to the `activation` key is largely the same JSON object as the [activation of standard OpenWhisk actions](actions-new.md#activation). The key difference is that `value` is not used under the `activation` key to pass parameters to the underlying function. To see the interface for passing keys to the underlying functions see section below.
+Example of an activation:
+```json
+{
+ "activation": {
+ "namespace": "",
+ "action_name": "hello",
+ "api_host": "",
+ "api_key": "",
+ "activation_id": "",
+ "transaction_id": "",
+ "deadline": 1000000
+ },
+ "value": {
+ "name": "Alan Turing",
+ "place": "England"
+ }
+}
+```
+One thing to note is when these values are present outside of the context of the OpenWhisk control plane, they may not actually be used for anything. However, the `activation` key is still necessary to signal the intent to run the function.
+
+## Passing parameters
+
+Similar to the description of the `value` key in the `activation` object during the [activation of standard OpenWhisk actions](actions-new.md#activation), a top level `value` key in the JSON object passed to the `/` endpoint (with a corresponding top level `activation` key) is how parameters are passed to the underlying function being run.
+In the following example:
+```json
+{
+ "activation": {
+ "namespace": "",
+ "action_name": "hello",
+ "api_host": "",
+ "api_key": "",
+ "activation_id": "",
+ "transaction_id": "",
+ "deadline": 1000000
+ },
+ "value": {
+ "name": "Alan Turing",
+ "location": "England"
+ }
+}
+```
+
+The underlying function would recieve a parameters map with the keys `name` and `location` with the values `Alan Turing` and `England` respectively.
+
+## Init/Run
+
+OpenWhisk stem cell runtimes being executed in a single entrypoint execution environment can be both initialized and activated at the same time by passing both `init` and `activation` keys in the same JSON object to the `/` endpoint. This will first initialize the runtime, following the same procedures described above, and then subsequently activate the same runtime.
+For example:
+```json
+{
+ "init": {
+ "name" : "hello",
+ "main" : "main",
+ "code" : "function main(params) {return { payload: 'Hello ' + params.name + ' from ' + params.place + '!' };}",
+ "binary": false,
+ "env": {}
+ },
+ "activation": {
+ "namespace": "",
+ "action_name": "hello",
+ "api_host": "",
+ "api_key": "",
+ "activation_id": "",
+ "transaction_id": "",
+ "deadline": 1000000
+ },
+ "value": {
+ "name": "Alan Turing",
+ "location": "England"
+ }
+}
+```
+The above JSON object would instruct the runtime to be initialized with the function under `init.code` and be run with the function being passed the object `{name: "Alan Turing", location: "England"}`. It would then return the JSON object
+```json
+{
+ "payload": "Hello Alan Turing from England!"
+}
+```
+
+## Example Cases
+Below is a table outlining the standardized behaviors that any action proxy implementation needs to fulfill. NodeJS was the sample language used, but corresponding example cases could be written in the language of the corresponding runtime it is showcasing.
+
+
+<table border="2" cellspacing="0" cellpadding="6" rules="groups" frame="hsides">
+
+
+<colgroup>
+<col/>
+
+<col/>
+
+<col/>
+
+<col/>
+
+<col/>
+
+<col/>
+
+<col/>
+</colgroup>
+<thead>
+<tr>
+<th scope="col" >Test Name</th>
+<th scope="col" >Action Code (In NodeJS)</th>
+<th scope="col" >Input</th>
Review comment:
They are linked further down in the Nodejs table
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
With regards,
Apache Git Services
[GitHub] [openwhisk] mrutkows commented on a change in pull request #4850:
Add single entrypoint proxy interface documentation
Posted by GitBox <gi...@apache.org>.
mrutkows commented on a change in pull request #4850: Add single entrypoint proxy interface documentation
URL: https://github.com/apache/openwhisk/pull/4850#discussion_r389900988
##########
File path: docs/single_entrypoint_proxy_contract.md
##########
@@ -0,0 +1,383 @@
+<!--
+#
+# Licensed to the Apache Software Foundation (ASF) under one or more
+# contributor license agreements. See the NOTICE file distributed with
+# this work for additional information regarding copyright ownership.
+# The ASF licenses this file to You under the Apache License, Version 2.0
+# (the "License"); you may not use this file except in compliance with
+# the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+-->
+# Action Proxy Single Entrypoint Interface
+
+The typical endpoints used by the OpenWhisk control plane are not used in single entrypoint execution environments such as Knative. Initialization and running are still essential to how OpenWhisk runtimes function, but they are done in a different methodology than `/init` and `/run` endpoints. The proxy that shapes how the calls are preprocessed and postprocessed to emulate some of the functionality provided by the OpenWhisk control plane. In single entrypoint supported runtime proxy implementations, both initailization and running are done via the `/` root endpoint. The sections below explain the interface the runtime proxy must adhere to initialize and run via a single entrypoint execution environment.
+
+## Init
+
+To initialize an undifferintiated stem cell, the interface is to pass a JSON object containing the key `init` to the `/` endpoint. The value corresponding to the `init` key is the same JSON object as the [initialization of standard OpenWhisk actions](actions-new.md#initialization). For example:
+```json
+{
+ "init": {
+ "name" : "hello",
+ "main" : "main",
+ "code" : "function main(params) {return { payload: 'Hello ' + params.name + ' from ' + params.place + '!' };}",
+ "binary": false,
+ "env": {}
+ }
+}
+```
+Just as with the OpenWhisk control plane, specialized function containers need no explicit initialization.
+
+## Run
+
+To run an action, the interface is to pass a JSON object containing the key `activation` to the `/` endpoint. The value corresponding to the `activation` key is largely the same JSON object as the [activation of standard OpenWhisk actions](actions-new.md#activation). The key difference is that `value` is not used under the `activation` key to pass parameters to the underlying function. To see the interface for passing keys to the underlying functions see section below.
+Example of an activation:
+```json
+{
+ "activation": {
+ "namespace": "",
+ "action_name": "hello",
+ "api_host": "",
+ "api_key": "",
+ "activation_id": "",
+ "transaction_id": "",
+ "deadline": 1000000
+ },
+ "value": {
+ "name": "Alan Turing",
+ "place": "England"
+ }
+}
+```
+One thing to note is when these values are present outside of the context of the OpenWhisk control plane, they may not actually be used for anything. However, the `activation` key is still necessary to signal the intent to run the function.
+
+## Passing parameters
+
+Similar to the description of the `value` key in the `activation` object during the [activation of standard OpenWhisk actions](actions-new.md#activation), a top level `value` key in the JSON object passed to the `/` endpoint (with a corresponding top level `activation` key) is how parameters are passed to the underlying function being run.
+In the following example:
+```json
+{
+ "activation": {
+ "namespace": "",
+ "action_name": "hello",
+ "api_host": "",
+ "api_key": "",
+ "activation_id": "",
+ "transaction_id": "",
+ "deadline": 1000000
+ },
+ "value": {
+ "name": "Alan Turing",
+ "location": "England"
+ }
+}
+```
+
+The underlying function would recieve a parameters map with the keys `name` and `location` with the values `Alan Turing` and `England` respectively.
+
+## Init/Run
+
+OpenWhisk stem cell runtimes being executed in a single entrypoint execution environment can be both initialized and activated at the same time by passing both `init` and `activation` keys in the same JSON object to the `/` endpoint. This will first initialize the runtime, following the same procedures described above, and then subsequently activate the same runtime.
+For example:
+```json
+{
+ "init": {
+ "name" : "hello",
+ "main" : "main",
+ "code" : "function main(params) {return { payload: 'Hello ' + params.name + ' from ' + params.place + '!' };}",
+ "binary": false,
+ "env": {}
+ },
+ "activation": {
+ "namespace": "",
+ "action_name": "hello",
+ "api_host": "",
+ "api_key": "",
+ "activation_id": "",
+ "transaction_id": "",
+ "deadline": 1000000
+ },
+ "value": {
+ "name": "Alan Turing",
+ "location": "England"
+ }
+}
+```
+The above JSON object would instruct the runtime to be initialized with the function under `init.code` and be run with the function being passed the object `{name: "Alan Turing", location: "England"}`. It would then return the JSON object
+```json
+{
+ "payload": "Hello Alan Turing from England!"
+}
+```
+
+## Example Cases
+Below is a table outlining the standardized behaviors that any action proxy implementation needs to fulfill. NodeJS was the sample language used, but corresponding example cases could be written in the language of the corresponding runtime it is showcasing.
+
+
+<table border="2" cellspacing="0" cellpadding="6" rules="groups" frame="hsides">
+
+
+<colgroup>
+<col/>
+
+<col/>
+
+<col/>
+
+<col/>
+
+<col/>
+
+<col/>
+
+<col/>
+</colgroup>
+<thead>
+<tr>
+<th scope="col" >Test Name</th>
+<th scope="col" >Action Code (In NodeJS)</th>
+<th scope="col" >Input</th>
Review comment:
Can we please link to the JSON files since they are now merged into openwhisk-test?
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
With regards,
Apache Git Services
[GitHub] [openwhisk] pwplusnick commented on issue #4850: Add single
entrypoint proxy interface documentation
Posted by GitBox <gi...@apache.org>.
pwplusnick commented on issue #4850: Add single entrypoint proxy interface documentation
URL: https://github.com/apache/openwhisk/pull/4850#issuecomment-595504661
https://github.com/apache/openwhisk/pull/4850/commits/31df9a6e13a6fbbf0530e944b804d8abc8a3bb97
Note this is the version you should look at for file changes. The last few commits were just me trying to get a markdown table working, but it doesn't look like it will pan out.
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
With regards,
Apache Git Services