morsapaes commented on a change in pull request #132:
URL: https://github.com/apache/flink-statefun/pull/132#discussion_r474611376
##########
File path: docs/sdk/index.md
##########
@@ -25,3 +25,109 @@ KIND, either express or implied. See the License for the
specific language governing permissions and limitations
under the License.
-->
+
+Stateful Functions applications are composed of one or more modules.
+A module is a bundle of functions that are loaded by the runtime and available
to be messaged.
+Functions from all loaded modules are multiplexed and free to message each
other arbitrarily.
+
+Stateful Functions supports two types of modules: Embedded and Remote.
+
+* This will be replaced by the TOC
+{:toc}
+
+## Remote Module
+
+Remote modules run as external processes from the Apache Flink® runtime; in
the same container, as a sidecar, using a serverless platform or other external
location.
+This module type can support any number of language SDKs.
+Remote modules are registered with the system via ``YAML`` configuration files.
+
+### Specification
+
+A remote module configuration consists of a ``meta`` section and a ``spec``
section.
+``meta`` contains auxillary information about the module.
+The ``spec`` describes the functions contained within the module and defines
their persisted values.
+
+### Defining Functions
+
+``module.spec.functions`` declares a list of ``function`` objects that are
implemented by the remote module.
+A ``function`` is described via a number of properties.
+
+* ``function.meta.kind``
+ * The protocol used to communicate with the remote function.
+ * Supported Values - ``http``
Review comment:
Making these consistent (more below).
##########
File path: docs/sdk/index.md
##########
@@ -25,3 +25,109 @@ KIND, either express or implied. See the License for the
specific language governing permissions and limitations
under the License.
-->
+
+Stateful Functions applications are composed of one or more modules.
+A module is a bundle of functions that are loaded by the runtime and available
to be messaged.
+Functions from all loaded modules are multiplexed and free to message each
other arbitrarily.
+
+Stateful Functions supports two types of modules: Embedded and Remote.
+
+* This will be replaced by the TOC
+{:toc}
+
+## Remote Module
+
+Remote modules run as external processes from the Apache Flink® runtime; in
the same container, as a sidecar, using a serverless platform or other external
location.
+This module type can support any number of language SDKs.
+Remote modules are registered with the system via ``YAML`` configuration files.
+
+### Specification
+
+A remote module configuration consists of a ``meta`` section and a ``spec``
section.
+``meta`` contains auxillary information about the module.
+The ``spec`` describes the functions contained within the module and defines
their persisted values.
+
+### Defining Functions
+
+``module.spec.functions`` declares a list of ``function`` objects that are
implemented by the remote module.
+A ``function`` is described via a number of properties.
Review comment:
```suggestion
A ``function`` is described via a number of properties:
```
##########
File path: docs/sdk/index.md
##########
@@ -25,3 +25,109 @@ KIND, either express or implied. See the License for the
specific language governing permissions and limitations
under the License.
-->
+
+Stateful Functions applications are composed of one or more modules.
+A module is a bundle of functions that are loaded by the runtime and available
to be messaged.
+Functions from all loaded modules are multiplexed and free to message each
other arbitrarily.
+
+Stateful Functions supports two types of modules: Embedded and Remote.
+
+* This will be replaced by the TOC
+{:toc}
+
+## Remote Module
+
+Remote modules run as external processes from the Apache Flink® runtime; in
the same container, as a sidecar, using a serverless platform or other external
location.
+This module type can support any number of language SDKs.
+Remote modules are registered with the system via ``YAML`` configuration files.
+
+### Specification
+
+A remote module configuration consists of a ``meta`` section and a ``spec``
section.
+``meta`` contains auxillary information about the module.
+The ``spec`` describes the functions contained within the module and defines
their persisted values.
+
+### Defining Functions
+
+``module.spec.functions`` declares a list of ``function`` objects that are
implemented by the remote module.
+A ``function`` is described via a number of properties.
+
+* ``function.meta.kind``
+ * The protocol used to communicate with the remote function.
+ * Supported Values - ``http``
Review comment:
```suggestion
* Supported values: ``http``
```
##########
File path: docs/sdk/index.md
##########
@@ -25,3 +25,109 @@ KIND, either express or implied. See the License for the
specific language governing permissions and limitations
under the License.
-->
+
+Stateful Functions applications are composed of one or more modules.
+A module is a bundle of functions that are loaded by the runtime and available
to be messaged.
+Functions from all loaded modules are multiplexed and free to message each
other arbitrarily.
+
+Stateful Functions supports two types of modules: Embedded and Remote.
+
+* This will be replaced by the TOC
+{:toc}
+
+## Remote Module
+
+Remote modules run as external processes from the Apache Flink® runtime; in
the same container, as a sidecar, using a serverless platform or other external
location.
+This module type can support any number of language SDKs.
+Remote modules are registered with the system via ``YAML`` configuration files.
+
+### Specification
+
+A remote module configuration consists of a ``meta`` section and a ``spec``
section.
+``meta`` contains auxillary information about the module.
+The ``spec`` describes the functions contained within the module and defines
their persisted values.
+
+### Defining Functions
+
+``module.spec.functions`` declares a list of ``function`` objects that are
implemented by the remote module.
+A ``function`` is described via a number of properties.
+
+* ``function.meta.kind``
+ * The protocol used to communicate with the remote function.
+ * Supported Values - ``http``
+* ``function.meta.type``
+ * The function type, defined as ``<namespace>/<name>``.
+* ``function.spec.endpoint``
+ * The endpoint at which the function is reachable.
+ * Supported schemes are: ``http``, ``https``.
+ * Transport via UNIX domain sockets is supported by using the schemes
``http+unix`` or ``https+unix``.
+ * When using UNIX domain sockets, the endpoint format is:
``http+unix://<socket-file-path>/<serve-url-path>``. For example,
``http+unix:///uds.sock/path/of/url``.
+* ``function.spec.states``
+ * A list of the persisted values declared within the remote function.
+ * Each entry consists of a `name` property and an optional `expireAfter`
property.
+ * Default for `expireAfter` - 0, meaning that state expiration is disabled.
+* ``function.spec.maxNumBatchRequests``
+ * The maximum number of records that can be processed by a function for a
particular ``address`` before invoking backpressure on the system.
+ * Default - 1000
+* ``function.spec.timeout``
+ * The maximum amount of time for the runtime to wait for the remote
function to return before failing.
+ * Default - 1 min
+
+### Full Example
+
+{% highlight yaml %}
+version: "2.0"
+
+module:
+ meta:
+ type: remote
+ spec:
+ functions:
+ - function:
+ meta:
+ kind: http
+ type: example/greeter
+ spec:
+ endpoint: http://<host-name>/statefun
+ states:
+ - name: seen_count
+ expireAfter: 5min
+ maxNumBatchRequests: 500
+ timeout: 2min
+{% endhighlight %}
+
+## Embedded Module
+
+Embedded modules are co-located with, and embedded within, the Apache Flink®
runtime.
+
+This module type only supports JVM based languages and are defined by
implementing the ``StatefulFunctionModule`` interface.
+Embedded modules offer a single configuration method where stateful functions
bind to the system based on their [function type]({{ site.baseurl
}}/concepts/logical.html#function-address).
+Runtime configurations are available through the ``globalConfiguration``,
which is the union of all configurations in the applications
``flink-conf.yaml`` under the prefix ``statefun.module.global-config`` and any
command line arguments passed in the form ``--key value``.
Review comment:
```suggestion
This module type only supports JVM-based languages and is defined by
implementing the ``StatefulFunctionModule`` interface.
Embedded modules offer a single configuration method where stateful
functions bind to the system based on their [function type]({{ site.baseurl
}}/concepts/logical.html#function-address).
Runtime configurations are available through the ``globalConfiguration``,
which is the union of all configurations in the applications
``flink-conf.yaml`` under the prefix ``statefun.module.global-config``, and any
command line arguments passed in the form ``--key value``.
```
##########
File path: docs/sdk/index.md
##########
@@ -25,3 +25,109 @@ KIND, either express or implied. See the License for the
specific language governing permissions and limitations
under the License.
-->
+
+Stateful Functions applications are composed of one or more modules.
+A module is a bundle of functions that are loaded by the runtime and available
to be messaged.
+Functions from all loaded modules are multiplexed and free to message each
other arbitrarily.
+
+Stateful Functions supports two types of modules: Embedded and Remote.
Review comment:
To keep up with the order you used below.
##########
File path: docs/sdk/index.md
##########
@@ -25,3 +25,109 @@ KIND, either express or implied. See the License for the
specific language governing permissions and limitations
under the License.
-->
+
+Stateful Functions applications are composed of one or more modules.
+A module is a bundle of functions that are loaded by the runtime and available
to be messaged.
+Functions from all loaded modules are multiplexed and free to message each
other arbitrarily.
+
+Stateful Functions supports two types of modules: Embedded and Remote.
Review comment:
```suggestion
Stateful Functions supports two types of modules: Remote and Embedded.
```
##########
File path: docs/sdk/index.md
##########
@@ -25,3 +25,109 @@ KIND, either express or implied. See the License for the
specific language governing permissions and limitations
under the License.
-->
+
+Stateful Functions applications are composed of one or more modules.
+A module is a bundle of functions that are loaded by the runtime and available
to be messaged.
+Functions from all loaded modules are multiplexed and free to message each
other arbitrarily.
+
+Stateful Functions supports two types of modules: Embedded and Remote.
+
+* This will be replaced by the TOC
+{:toc}
+
+## Remote Module
+
+Remote modules run as external processes from the Apache Flink® runtime; in
the same container, as a sidecar, using a serverless platform or other external
location.
+This module type can support any number of language SDKs.
+Remote modules are registered with the system via ``YAML`` configuration files.
+
+### Specification
+
+A remote module configuration consists of a ``meta`` section and a ``spec``
section.
+``meta`` contains auxillary information about the module.
+The ``spec`` describes the functions contained within the module and defines
their persisted values.
Review comment:
```suggestion
The ``meta`` section contains auxiliary information about the module; while
``spec`` describes the functions contained within the module and defines their
persisted values.
```
##########
File path: docs/index.md
##########
@@ -23,16 +23,19 @@ specific language governing permissions and limitations
under the License.
-->
-**Stateful Functions** is an open source framework that reduces the complexity
of building and orchestrating distributed stateful applications at scale.
-It brings together the benefits of stream processing with Apache Flink® and
Function-as-a-Service (FaaS) to provide a powerful abstraction for the next
generation of event-driven architectures.
+Stateful Functions is an API that simplifies the building of **distributed
stateful applications** with a **runtime built for serverless architectures**.
+It brings together the benefits of stateful stream processing, the processing
of large datasets with low latency and bounded resource constraints,
Review comment:
This confuses me a bit because of punctuation (🙄). Is "the processing of
large datasets with low latency and bounded resource constraints" the unfold of
"the benefits of stateful stream processing" or do you mean it as a separate
"benefit"?
Other than that, I really like the rephrasing!
##########
File path: docs/sdk/index.md
##########
@@ -25,3 +25,109 @@ KIND, either express or implied. See the License for the
specific language governing permissions and limitations
under the License.
-->
+
+Stateful Functions applications are composed of one or more modules.
+A module is a bundle of functions that are loaded by the runtime and available
to be messaged.
Review comment:
```suggestion
A module is a bundle of functions that are loaded by the runtime and become
available to be messaged.
```
##########
File path: docs/sdk/index.md
##########
@@ -25,3 +25,109 @@ KIND, either express or implied. See the License for the
specific language governing permissions and limitations
under the License.
-->
+
+Stateful Functions applications are composed of one or more modules.
+A module is a bundle of functions that are loaded by the runtime and available
to be messaged.
+Functions from all loaded modules are multiplexed and free to message each
other arbitrarily.
+
+Stateful Functions supports two types of modules: Embedded and Remote.
+
+* This will be replaced by the TOC
+{:toc}
+
+## Remote Module
+
+Remote modules run as external processes from the Apache Flink® runtime; in
the same container, as a sidecar, using a serverless platform or other external
location.
+This module type can support any number of language SDKs.
+Remote modules are registered with the system via ``YAML`` configuration files.
+
+### Specification
+
+A remote module configuration consists of a ``meta`` section and a ``spec``
section.
+``meta`` contains auxillary information about the module.
+The ``spec`` describes the functions contained within the module and defines
their persisted values.
+
+### Defining Functions
+
+``module.spec.functions`` declares a list of ``function`` objects that are
implemented by the remote module.
+A ``function`` is described via a number of properties.
+
+* ``function.meta.kind``
+ * The protocol used to communicate with the remote function.
+ * Supported Values - ``http``
+* ``function.meta.type``
+ * The function type, defined as ``<namespace>/<name>``.
+* ``function.spec.endpoint``
+ * The endpoint at which the function is reachable.
+ * Supported schemes are: ``http``, ``https``.
+ * Transport via UNIX domain sockets is supported by using the schemes
``http+unix`` or ``https+unix``.
+ * When using UNIX domain sockets, the endpoint format is:
``http+unix://<socket-file-path>/<serve-url-path>``. For example,
``http+unix:///uds.sock/path/of/url``.
+* ``function.spec.states``
+ * A list of the persisted values declared within the remote function.
+ * Each entry consists of a `name` property and an optional `expireAfter`
property.
+ * Default for `expireAfter` - 0, meaning that state expiration is disabled.
+* ``function.spec.maxNumBatchRequests``
+ * The maximum number of records that can be processed by a function for a
particular ``address`` before invoking backpressure on the system.
+ * Default - 1000
+* ``function.spec.timeout``
+ * The maximum amount of time for the runtime to wait for the remote
function to return before failing.
+ * Default - 1 min
Review comment:
```suggestion
* Default: 1 min
```
##########
File path: docs/sdk/index.md
##########
@@ -25,3 +25,109 @@ KIND, either express or implied. See the License for the
specific language governing permissions and limitations
under the License.
-->
+
+Stateful Functions applications are composed of one or more modules.
+A module is a bundle of functions that are loaded by the runtime and available
to be messaged.
+Functions from all loaded modules are multiplexed and free to message each
other arbitrarily.
+
+Stateful Functions supports two types of modules: Embedded and Remote.
+
+* This will be replaced by the TOC
+{:toc}
+
+## Remote Module
+
+Remote modules run as external processes from the Apache Flink® runtime; in
the same container, as a sidecar, using a serverless platform or other external
location.
+This module type can support any number of language SDKs.
+Remote modules are registered with the system via ``YAML`` configuration files.
+
+### Specification
+
+A remote module configuration consists of a ``meta`` section and a ``spec``
section.
+``meta`` contains auxillary information about the module.
+The ``spec`` describes the functions contained within the module and defines
their persisted values.
+
+### Defining Functions
+
+``module.spec.functions`` declares a list of ``function`` objects that are
implemented by the remote module.
+A ``function`` is described via a number of properties.
+
+* ``function.meta.kind``
+ * The protocol used to communicate with the remote function.
+ * Supported Values - ``http``
+* ``function.meta.type``
+ * The function type, defined as ``<namespace>/<name>``.
+* ``function.spec.endpoint``
+ * The endpoint at which the function is reachable.
+ * Supported schemes are: ``http``, ``https``.
Review comment:
```suggestion
* Supported schemes: ``http``, ``https``.
```
##########
File path: docs/sdk/index.md
##########
@@ -25,3 +25,109 @@ KIND, either express or implied. See the License for the
specific language governing permissions and limitations
under the License.
-->
+
+Stateful Functions applications are composed of one or more modules.
+A module is a bundle of functions that are loaded by the runtime and available
to be messaged.
+Functions from all loaded modules are multiplexed and free to message each
other arbitrarily.
+
+Stateful Functions supports two types of modules: Embedded and Remote.
+
+* This will be replaced by the TOC
+{:toc}
+
+## Remote Module
+
+Remote modules run as external processes from the Apache Flink® runtime; in
the same container, as a sidecar, using a serverless platform or other external
location.
+This module type can support any number of language SDKs.
+Remote modules are registered with the system via ``YAML`` configuration files.
+
+### Specification
+
+A remote module configuration consists of a ``meta`` section and a ``spec``
section.
+``meta`` contains auxillary information about the module.
+The ``spec`` describes the functions contained within the module and defines
their persisted values.
+
+### Defining Functions
+
+``module.spec.functions`` declares a list of ``function`` objects that are
implemented by the remote module.
+A ``function`` is described via a number of properties.
+
+* ``function.meta.kind``
+ * The protocol used to communicate with the remote function.
+ * Supported Values - ``http``
+* ``function.meta.type``
+ * The function type, defined as ``<namespace>/<name>``.
+* ``function.spec.endpoint``
+ * The endpoint at which the function is reachable.
+ * Supported schemes are: ``http``, ``https``.
+ * Transport via UNIX domain sockets is supported by using the schemes
``http+unix`` or ``https+unix``.
+ * When using UNIX domain sockets, the endpoint format is:
``http+unix://<socket-file-path>/<serve-url-path>``. For example,
``http+unix:///uds.sock/path/of/url``.
+* ``function.spec.states``
+ * A list of the persisted values declared within the remote function.
+ * Each entry consists of a `name` property and an optional `expireAfter`
property.
+ * Default for `expireAfter` - 0, meaning that state expiration is disabled.
+* ``function.spec.maxNumBatchRequests``
+ * The maximum number of records that can be processed by a function for a
particular ``address`` before invoking backpressure on the system.
+ * Default - 1000
Review comment:
```suggestion
* Default: 1000
```
----------------------------------------------------------------
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:
us...@infra.apache.org
