This is an automated email from the ASF dual-hosted git repository.
franztt pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/openserverless-site.git
The following commit(s) were added to refs/heads/main by this push:
new 6031821 Reviewed entities (#47)
6031821 is described below
commit 603182118069238bfccdbf47c7225e048d1ab371
Author: Bruno Salzano <[email protected]>
AuthorDate: Sun Nov 3 00:28:14 2024 +0100
Reviewed entities (#47)
* chore: disabled repo
Disabled links on right sidebar
* docs: entities
Reviewed entities
---
content/en/docs/reference/entities/_index.md | 18 +----
.../en/docs/reference/entities/actions/_index.md | 12 ++--
.../docs/reference/entities/annotations/_index.md | 21 +++---
content/en/docs/reference/entities/feeds/_index.md | 29 ++++----
.../en/docs/reference/entities/packages/_index.md | 6 +-
.../docs/reference/entities/parameters/_index.md | 17 +++--
.../docs/reference/entities/webactions/_index.md | 83 +++++++++++-----------
7 files changed, 90 insertions(+), 96 deletions(-)
diff --git a/content/en/docs/reference/entities/_index.md
b/content/en/docs/reference/entities/_index.md
index 0e5ba9f..fdd07de 100644
--- a/content/en/docs/reference/entities/_index.md
+++ b/content/en/docs/reference/entities/_index.md
@@ -1,19 +1,7 @@
---
title: Entities
+description:
+weight: 10
---
-You can find more informations about OpenServerless and OpenWhisk entities
-here:
-- [Actions](#actions.adoc)
-
-- [Parameters](#parameters.adoc)
-
-- [Annotations](#annotations.adoc)
-
-- [Scheduler](#scheduler.adoc)
-
-- [Web Actions](#webactions.adoc)
-
-- [Packages](#packages.adoc)
-
-- [Feeds](#feeds.adoc)
+In this section you can find more informations about OpenServerless and
OpenWhisk entities.
diff --git a/content/en/docs/reference/entities/actions/_index.md
b/content/en/docs/reference/entities/actions/_index.md
index 5b508e2..4fa3831 100644
--- a/content/en/docs/reference/entities/actions/_index.md
+++ b/content/en/docs/reference/entities/actions/_index.md
@@ -12,23 +12,21 @@ call, or post a Tweet. In general, an action is invoked in
response to
an event and produces some observable output.
An action may be created from a function programmed using a number of
-[supported languages and
-runtimes](/docs/reference/index-runtimes), or from a
+[supported languages and runtimes](/docs/reference/runtimes/), or from a
binary-compatible executable.
- The OpenServerless CLI makes it easy to create and invoke actions.
Instructions for configuring and using the CLI are available
[here](/docs/cli/).
-- You can also use the [REST
- API](/docs/reference/rest_api/).
+- You can also use the [REST API](/docs/reference/rest_api/).
While the actual function code will be specific to a [language and
-runtime](/docs/reference/index-runtimes/), the operations to
+runtime](/docs/reference/runtimes/), the operations to
create, invoke and manage an action are the same regardless of the
implementation choice.
-We recommend that you review [the cli](#../../cli/index.adoc) and read
+We recommend that you review [the cli](/docs/cli/) and read
[the tutorial](#../../tutorial/index.adoc) before moving on to advanced
topics.
@@ -88,7 +86,7 @@ OpenWhisk and OpenServerless Docker skeleton.
- `__OW_API_KEY` the API key for the subject invoking the action, this
key may be a restricted API key. This property is absent unless
requested with the annotation explicitly
-
[`provide-api-key`](#../../reference/annotations/index.adoc#annotations-for-all-actions)
+
[`provide-api-key`](/docs/reference/entities/annotations/#annotations-for-all-actions)
- `__OW_NAMESPACE` the namespace for the *activation* (this may not be
the same as the namespace for the action).
diff --git a/content/en/docs/reference/entities/annotations/_index.md
b/content/en/docs/reference/entities/annotations/_index.md
index 1ffc51a..603931a 100644
--- a/content/en/docs/reference/entities/annotations/_index.md
+++ b/content/en/docs/reference/entities/annotations/_index.md
@@ -1,8 +1,10 @@
---
title: Annotations
-weigth: 40
+description: How to use annotations to decorate actions
+weight: 40
---
-# Annotations
+
+## Annotations
OpenWhisk and OpenServerless actions, triggers, rules and packages
(collectively referred to as assets) may be decorated with
@@ -78,6 +80,8 @@ The annotations are *not* checked. So while it is conceivable
to use the
annotations to infer if a composition of two actions into a sequence is
legal, for example, the system does not yet do that.
+## Annotations for all actions
+
The following annotations on an action are available.
- `provide-api-key`: This annotation may be attached to actions which
@@ -87,20 +91,19 @@ The following annotations on an action are available.
absence of this annotation, or its presence with a value that is not
*falsy* (i.e., a value that is different from zero, null, false, and
the empty string) will cause an API key to be present in the [action
- execution
- context](#actions.adoc#accessing-action-metadata-within-the-action-body).
+ execution
context](../actions/#accessing-action-metadata-within-the-action-body).
-# Annotations specific to web actions
+## Annotations specific to web actions
Web actions are enabled with explicit annotations which decorate
individual actions. The annotations only apply to the [web
-actions](#webactions.adoc) API, and must be present and explicitly set
+actions](../webactions/) API, and must be present and explicitly set
to `true` to have an affect. The annotations have no meaning otherwise
in the system. The annotations are:
- `web-export`: Makes its corresponding action accessible to REST
calls *without* authentication. We call these [*web
- actions*](#webactions.adoc) because they allow one to use OpenWhisk
+ actions*](../webactions/) because they allow one to use OpenWhisk
and OpenServerless actions from a browser for example. It is important to
note that the *owner* of the web action incurs the cost of running
them in the system (i.e., the *owner* of the action also owns the
@@ -118,7 +121,7 @@ in the system. The annotations are:
- `web-custom-options`: When set, this annotation enables a web action
to respond to OPTIONS requests with customized headers, otherwise a
- [default CORS response](#webactions.adoc#options-requests) applies.
+ [default CORS response](../webactions/#options-requests) applies.
- `require-whisk-auth`: This annotation protects the web action so
that it is only invoked by requests that provide appropriate
@@ -133,7 +136,7 @@ in the system. The annotations are:
system (i.e., the *owner* of the action also owns the activations
record).
-# Annotations specific to activations
+## Annotations specific to activations
The system decorates activation records with annotations as well. They
are:
diff --git a/content/en/docs/reference/entities/feeds/_index.md
b/content/en/docs/reference/entities/feeds/_index.md
index 4a7c12f..73bc2c1 100644
--- a/content/en/docs/reference/entities/feeds/_index.md
+++ b/content/en/docs/reference/entities/feeds/_index.md
@@ -1,8 +1,8 @@
---
title: Feeds
+description: Implement Feeds
weight: 60
---
-# Implementing feeds
OpenWhisk and OpenServerless support an open API, where any user can expose
an event producer service as a **feed** in a **package**. This section
@@ -13,12 +13,12 @@ This material is intended for advanced OpenWhisk and
OpenServerless users who
intend to publish their own feeds. Most OpenWhisk and OpenServerless users
can safely skip this section.
-# Feed Architecture
+## Feed Architecture
There are at least 3 architectural patterns for creating a feed:
**Hooks**, **Polling** and **Connections**.
-## Hooks
+### Hooks
In the *Hooks* pattern, we set up a feed using a
[webhook](https://en.wikipedia.org/wiki/Webhook) facility exposed by
@@ -26,21 +26,21 @@ another service. In this strategy, we configure a webhook
on an external
service to POST directly to a URL to fire a trigger. This is by far the
easiest and most attractive option for implementing low-frequency feeds.
-## Polling
+### Polling
In the `Polling` pattern, we arrange for an OpenWhisk and OpenServerless
*action* to poll an endpoint periodically to fetch new data. This
pattern is relatively easy to build, but the frequency of events will of
course be limited by the polling interval.
-## Connections
+### Connections
In the `Connections` pattern, we stand up a separate service somewhere
that maintains a persistent connection to a feed source. The connection
based implementation might interact with a service endpoint via long
polling, or to set up a push notification.
-# Difference between Feed and Trigger
+## Difference between Feed and Trigger
Feeds and triggers are closely related, but technically distinct
concepts.
@@ -61,13 +61,14 @@ concepts.
services which produce the events, via a REST API that manages
notifications.
-# Implementing Feed Actions
+## Implementing Feed Actions
The *feed action* is a normal OpenWhisk and OpenServerless *action*, but it
-should accept the following parameters: \* **lifecycleEvent**: one of
-‘CREATE’, ‘READ’, ‘UPDATE’, ‘DELETE’, ‘PAUSE’, or ‘UNPAUSE’. \*
-**triggerName**: the fully-qualified name of the trigger which contains
-events produced from this feed. \* **authKey**: the Basic auth
+should accept the following parameters:
+ - **lifecycleEvent**: one of ‘CREATE’, ‘READ’, ‘UPDATE’, ‘DELETE’, ‘PAUSE’,
or ‘UNPAUSE’.
+ - **triggerName**: the fully-qualified name of the trigger which contains
+events produced from this feed.
+- **authKey**: the Basic auth
credentials of the OpenWhisk and OpenServerless user who owns the trigger
just mentioned.
@@ -101,7 +102,7 @@ architecture. We’ll discuss the other architectures below.
A similar feed action protocol occurs for `ops trigger delete`,
`ops trigger update` and `ops trigger get`.
-# Implementing Feeds with Hooks
+## Implementing Feeds with Hooks
It is easy to set up a feed via a hook if the event producer supports a
webhook/callback facility.
@@ -124,7 +125,7 @@ defining parameters on the trigger event. OpenWhisk and
OpenServerless rules
pass these trigger parameters to any actions to fire as a result of the
event.
-# Implementing Feeds with Polling
+## Implementing Feeds with Polling
It is possible to set up an OpenWhisk and OpenServerless *action* to poll a
feed source entirely within OpenWhisk and OpenServerless, without the need to
@@ -148,7 +149,7 @@ This procedure implements a polling-based trigger entirely
using
OpenWhisk and OpenServerless actions, without any need for a separate
service.
-# Implementing Feeds via Connections
+## Implementing Feeds via Connections
The previous 2 architectural choices are simple and easy to implement.
However, if you want a high-performance feed, there is no substitute for
diff --git a/content/en/docs/reference/entities/packages/_index.md
b/content/en/docs/reference/entities/packages/_index.md
index ffd2e98..4aef17e 100644
--- a/content/en/docs/reference/entities/packages/_index.md
+++ b/content/en/docs/reference/entities/packages/_index.md
@@ -1,8 +1,8 @@
---
title: Packages
+description: Create and Use packages
weight: 50
---
-# Using and creating packages
In OpenWhisk and OpenServerless, you can use packages to bundle together a
set of related actions, and share them with others.
@@ -17,7 +17,7 @@ fire a trigger at a specified frequency.
Every OpenWhisk and OpenServerless entity, including packages, belongs in a
*namespace*, and the fully qualified name of an entity is
`/namespaceName[/packageName]/entityName`. Refer to the [naming
-guidelines](#reference.adoc#openwhisk-entities) for more information.
+guidelines](/docs/reference/references/naming-limits/#entities) for more
information.
The following sections describe how to browse packages and use the
triggers and feeds in them. In addition, if you are interested in
@@ -55,7 +55,7 @@ and get a description of the individual entities in a package.
**Note**: Parameters listed under the package with a prefix `*` are
predefined, bound parameters. Parameters without a `*` are those listed
-under the [annotations](#annotations.adoc) for each entity. Furthermore,
+under the [annotations](/docs/reference/entities/annotations/) for each
entity. Furthermore,
any parameters with the prefix `**` are finalized bound parameters. This
means that they are immutable, and cannot be changed by the user. Any
entity listed under a package inherits specific bound parameters from
diff --git a/content/en/docs/reference/entities/parameters/_index.md
b/content/en/docs/reference/entities/parameters/_index.md
index 0025383..9963db8 100644
--- a/content/en/docs/reference/entities/parameters/_index.md
+++ b/content/en/docs/reference/entities/parameters/_index.md
@@ -1,7 +1,11 @@
---
title: Parameters
+description: Supply data to actions adding parameters
weight: 30
---
+
+## Introduction to parameters
+
When working with serverless actions, data is supplied by adding
parameters to the actions; these are in the parameter declared as an
argument to the main serverless function. All data arrives this way and
@@ -19,11 +23,10 @@ is also information on how to use a file to store the
parameters and
pass the filename, rather than supplying each parameter individually on
the command-line.
-# Passing parameters to an action at invoke time
+## Passing parameters to an action at invoke time
Parameters can be passed to the action when it is invoked. These
-examples use JavaScript but all [the other
-languages](#index-runtimes.adoc) work the same way.
+examples use JavaScript but all [the other
languages](/docs/reference/runtimes/) work the same way.
1. Use parameters in the action. For example, create ‘hello.js’ file
with the following content:
@@ -80,7 +83,7 @@ The result is the same because the CLI automatically parses
the `person`
parameter value into the structured object that the action now expects:
`json { "payload": "Hello, Dorothy from Kansas" }`
-# Setting default parameters on an action
+## Setting default parameters on an action
Actions can be invoked with multiple named parameters. Recall that the
`hello` action from the previous example expects two parameters: the
@@ -93,7 +96,7 @@ parameter so that the action defaults to the place “Kansas”:
1. Update the action by using the `--param` option to bind parameter
values, or by passing a file that contains the parameters to
`--param-file` (for examples of using files, see the section on
- [working with parameter files](##working-with-parameter-files)).
+ [working with parameter files](#working-with-parameter-files).
To specify default parameters explicitly on the command-line, provide a
key/value pair to the `param` flag:
@@ -128,7 +131,7 @@ specifying the parameter value at invocation time.
Despite a parameter set on the action when it was created/updated, this
is overridden by a parameter that was supplied when invoking the action.
-# Setting default parameters on a package
+## Setting default parameters on a package
Parameters can be set at the package level, and these will serve as
default parameters for actions unless:
@@ -167,7 +170,7 @@ package and shows an action making use of it.
"payload": "Hello, World"
}
-\# Working with parameter files
+## Working with parameter files
It’s also possible to put parameters into a file in JSON format, and
then pass the parameters in by supplying the filename with the
diff --git a/content/en/docs/reference/entities/webactions/_index.md
b/content/en/docs/reference/entities/webactions/_index.md
index 9d0908f..0a3f588 100644
--- a/content/en/docs/reference/entities/webactions/_index.md
+++ b/content/en/docs/reference/entities/webactions/_index.md
@@ -1,15 +1,17 @@
---
title: Web Actions
+description: Actions annotated to quickly build web based applications
weight: 20
---
-# Web Actions
+
+## What web actions are
Web actions are OpenWhisk and OpenServerless actions annotated to quickly
enable you to build web based applications. This allows you to program
backend logic which your web application can access anonymously without
requiring an OpenWhisk and OpenServerless authentication key. It is up to the
action developer to implement their own desired authentication and
-authorization (i.e. OAuth flow).
+authorization (i.e.OAuth flow).
Web action activations will be associated with the user that created the
action. This actions defers the cost of an action activation from the
@@ -53,7 +55,7 @@ namespace, the package name, and the action name.
which is `default` if the action is not in a named package.*
An example is `guest/demo/hello`. The last part of the URI called the
-`extension` which is typically `.http` although other values are
+`extension` which is typically `.http` although other values are
permitted as described later. The web action API path may be used with
`curl` or `wget` without an API key. It may even be entered directly in
your browser.
@@ -126,7 +128,7 @@ the body may be any allowed JSON value. The default
content-type may be
omitted from the headers.
It is important to be aware of the [response size
-limit](#reference.adoc) for actions since a response that exceeds the
+limit](/docs/reference/references/naming-limits/#actions) for actions since a
response that exceeds the
predefined system limits will fail. Large objects should not be sent
inline through OpenWhisk and OpenServerless, but instead deferred to an
object store, for example.
@@ -143,16 +145,16 @@ JSON object, but the OpenWhisk and OpenServerless system
(namely the
one or more of the following as top level JSON properties:
1. `headers`: a JSON object where the keys are header-names and the
- values are string, number, or boolean values for those headers
- (default is no headers). To send multiple values for a single
- header, the header’s value should be a JSON array of values.
+ values are string, number, or boolean values for those headers
+ (default is no headers). To send multiple values for a single
+ header, the header’s value should be a JSON array of values.
2. `statusCode`: a valid HTTP status code (default is 200 OK if body is
- not empty otherwise 204 No Content).
+ not empty otherwise 204 No Content).
3. `body`: a string which is either plain text, JSON object or array,
- or a base64 encoded string for binary data (default is empty
- response).
+ or a base64 encoded string for binary data (default is empty
+ response).
The `body` is considered empty if it is `null`, the empty string `""` or
undefined.
@@ -178,28 +180,27 @@ as parameters to the action input argument. They are:
2. `__ow_headers` (type: map string to string): the request headers.
3. `__ow_path` (type: string): the unmatched path of the request
- (matching stops after consuming the action extension).
+ (matching stops after consuming the action extension).
4. `__ow_user` (type: string): the namespace identifying the OpenWhisk
- and OpenServerless authenticated subject.
+ and OpenServerless authenticated subject.
5. `__ow_body` (type: string): the request body entity, as a base64
- encoded string when content is binary or JSON object/array, or plain
- string otherwise.
+ encoded string when content is binary or JSON object/array, or plain
+ string otherwise.
6. `__ow_query` (type: string): the query parameters from the request
- as an unparsed string.
+ as an unparsed string.
A request may not override any of the named `__ow_` parameters above;
doing so will result in a failed request with status equal to 400 Bad
Request.
The `__ow_user` is only present when the web action is [annotated to
-require
-authentication](#annotations.adoc#annotations-specific-to-web-actions)
+require authentication](../annotations/#annotations-specific-to-web-actions)
and allows a web action to implement its own authorization policy. The
`__ow_query` is available only when a web action elects to handle the
-[“raw” HTTP request](##raw-http-handling). It is a string containing the
+[“raw” HTTP request](#raw-http-handling). It is a string containing the
query parameters parsed from the URI (separated by `&`). The `__ow_body`
property is present either when handling “raw” HTTP requests, or when
the HTTP request entity is not a JSON object or form data. Web actions
@@ -213,33 +214,33 @@ parameters.
Web actions bring some additional features that include:
1. `Content extensions`: the request must specify its desired content
- type as one of `.json`, `.html`, `.http`, `.svg` or `.text`. This is
- done by adding an extension to the action name in the URI, so that
- an action `/guest/demo/hello` is referenced as
- `/guest/demo/hello.http` for example to receive an HTTP response
- back. For convenience, the `.http` extension is assumed when no
- extension is detected.
+ type as one of`.json`,`.html`,`.http`, `.svg` or `.text`. This is
+ done by adding an extension to the action name in the URI, so that
+ an action `/guest/demo/hello` is referenced as
+ `/guest/demo/hello.http` for example to receive an HTTP response
+ back. For convenience, the `.http` extension is assumed when no
+ extension is detected.
2. `Query and body parameters as input`: the action receives query
- parameters as well as parameters in the request body. The precedence
- order for merging parameters is: package parameters, binding
- parameters, action parameters, query parameter, body parameters with
- each of these overriding any previous values in case of overlap . As
- an example `/guest/demo/hello.http?name=Jane` will pass the argument
- `{name: "Jane"}` to the action.
+ parameters as well as parameters in the request body. The precedence
+ order for merging parameters is: package parameters, binding
+ parameters, action parameters, query parameter, body parameters with
+ each of these overriding any previous values in case of overlap . As
+ an example `/guest/demo/hello.http?name=Jane` will pass the argument
+ `{name: "Jane"}` to the action.
3. `Form data`: in addition to the standard `application/json`, web
- actions may receive URL encoded from data
- `application/x-www-form-urlencoded data` as input.
+ actions may receive URL encoded from data
+ `application/x-www-form-urlencoded data` as input.
4. `Activation via multiple HTTP verbs`: a web action may be invoked
- via any of these HTTP methods: `GET`, `POST`, `PUT`, `PATCH`, and
- `DELETE`, as well as `HEAD` and `OPTIONS`.
+ via any of these HTTP methods: `GET`, `POST`, `PUT`, `PATCH`, and
+ `DELETE`, as well as `HEAD` and `OPTIONS`.
5. `Non JSON body and raw HTTP entity handling`: A web action may
- accept an HTTP request body other than a JSON object, and may elect
- to always receive such values as opaque values (plain text when not
- binary, or base64 encoded string otherwise).
+ accept an HTTP request body other than a JSON object, and may elect
+ to always receive such values as opaque values (plain text when not
+ binary, or base64 encoded string otherwise).
The example below briefly sketches how you might use these features in a
web action. Consider an action `/guest/demo/hello` with the following
@@ -373,7 +374,7 @@ that try to change this value whether by accident or
intentionally.
By default, a web action can be invoked by anyone having the web
action’s invocation URL. Use the `require-whisk-auth` [web action
-annotation](#annotations.adoc#annotations-specific-to-web-actions) to
+annotation](../annotations/#annotations-specific-to-web-actions) to
secure the web action. When the `require-whisk-auth` annotation is set
to `true`, the action will authenticate the invocation request’s Basic
Authorization credentials to confirm they represent a valid OpenWhisk
@@ -415,7 +416,7 @@ A web action may elect to interpret and process an incoming
HTTP body
directly, without the promotion of a JSON object to first class
properties available to the action input (e.g., `args.name` vs parsing
`args.__ow_query`). This is done via a `raw-http`
-[annotation](#annotations.adoc). Using the same example show earlier,
+[annotation](/docs/reference/entities/annotations/#annotations). Using the
same example show earlier,
but now as a “raw” HTTP web action receiving `name` both as a query
parameters and as JSON value in the HTTP request body:
@@ -568,10 +569,10 @@ produce a response (this is similar to an uncaught
exception). For web
actions, the controller handles application errors as follows:
1. The controller projects an `error` property from the response
- object.
+ object.
2. The controller applies the content handling implied by the action
- extension to the value of the `error` property.
+ extension to the value of the `error` property.
Developers should be aware of how web actions might be used and generate
error responses accordingly. For example, a web action that is used with
