Pdk 1.3 gr

pdk/1.3/antora.yml

@@ -0,0 +1,11 @@
+name: pdk
+title: 'Flex Gateway Policy Development Kit (PDK)'
+version: '1.3'
+display_version: '1.3'
+start_page: policies-pdk-overview.adoc
+asciidoc:
+  attributes:
+    rust-ver-var: 'v1.74.0'
+    template-policies-url-ver-var: '1.3.0'
+nav:
+- modules/ROOT/nav.adoc

pdk/1.3/modules/ROOT/_attributes.adoc

@@ -0,0 +1,4 @@
+:attachmentsdir: {moduledir}/assets/attachments
+:partialsdir: {moduledir}/pages/_partials
+:imagesdir: {moduledir}/assets/images
+:examplesdir: {moduledir}/examples

pdk/1.3/modules/ROOT/nav.adoc

@@ -0,0 +1,35 @@
+* xref:policies-pdk-overview.adoc[PDK Overview]
+* xref:policies-pdk-release-notes.adoc[Release Notes]
+* xref:policies-pdk-architecture.adoc[Architecture Overview]
+* xref:policies-pdk-prerequisites.adoc[]
+* xref:policies-pdk-upgrade-pdk.adoc[]
+* xref:policies-pdk-configure-network-proxy.adoc[]
+* xref:policies-pdk-develop-custom-policies.adoc[]
+** xref:policies-pdk-create-project.adoc[]
+** xref:policies-pdk-create-schema-definition.adoc[]
+** xref:policies-pdk-configure-features.adoc[]
+*** xref:policies-pdk-configure-features-logging.adoc[]
+*** xref:policies-pdk-configure-features-headers.adoc[]
+*** xref:policies-pdk-configure-features-inject-parameters.adoc[]
+*** xref:policies-pdk-configure-features-http-request.adoc[]
+*** xref:policies-pdk-configure-features-contracts.adoc[]
+*** xref:policies-pdk-configure-features-cors.adoc[]
+*** xref:policies-pdk-configure-features-jwt.adoc[]
+*** xref:policies-pdk-configure-features-dataweave.adoc[]
+*** xref:policies-pdk-configure-features-share-data.adoc[]
+*** xref:policies-pdk-configure-features-libraries.adoc[]
+*** xref:policies-pdk-configure-features-caching.adoc[]
+*** xref:policies-pdk-configure-features-metadata.adoc[]
+*** xref:policies-pdk-configure-features-streamproperties.adoc[]
+*** xref:policies-pdk-configure-features-authentication.adoc[]
+*** xref:policies-pdk-configure-features-timer.adoc[]
+*** xref:policies-pdk-configure-features-stop.adoc[]
+** xref:policies-pdk-compile-policies.adoc[]
+** xref:policies-pdk-debug-local.adoc[]
+** xref:policies-pdk-integration-tests.adoc[]
+** xref:policies-pdk-publish-policies.adoc[]
+* xref:policies-pdk-policy-templates.adoc[]
+* xref:policies-pdk-apply-policies.adoc[]
+* xref:policies-pdk-debug-deployed-policies.adoc[]
+* xref:policies-pdk-troubleshooting.adoc[Troubleshooting]
+

pdk/1.3/modules/ROOT/pages/_partials/pdk-spotlight-video.html

@@ -0,0 +1 @@
+<script type='text/javascript' async src='https://play.vidyard.com/embed/v4.js' data-playbackurl='play.vidyard.com'></script><img style='margin: auto; display: block; width: 100%; 'class='vidyard-player-embed' src='https://play.vidyard.com/ibt7HZ8SByp9VCn88dNPx7.jpg' data-height='540' data-width='960' data-width='auto' data-controller='hubs' data-action='show' data-uuid='ibt7HZ8SByp9VCn88dNPx7' data-type='inline' />

pdk/1.3/modules/ROOT/pages/policies-pdk-apply-policies.adoc

@@ -0,0 +1,109 @@
+= Applying Custom Policies
+ifndef::env-site,env-github[]
+include::_attributes.adoc[]
+endif::[]
+:imagesdir: ../assets/images
+
+Applying custom policies is the same as applying xref:gateway::policies-included-directory.adoc[included policies].
+
+When applying custom policies, the configuration parameters are defined in `definition/gcl.yaml`.
+
+To learn more about defining configuration parameters, see xref:policies-pdk-create-schema-definition.adoc[].
+
+== Before You Begin
+
+* xref:policies-pdk-compile-policies.adoc[Compile your custom policy].
+* If applying your custom policy to Flex Gateway running in Connected Mode, xref:policies-pdk-publish-policies.adoc[upload your custom policy to Exchange].
+
+== Apply Policies in Connected Mode
+
+When you apply a custom policy in Connected Mode, the configuration parameters and metadata defined in `gcl.yaml` appear in the API Manager UI.
+
+To apply a custom policy in Connected Mode, see xref:gateway::policies-included-apply.adoc[Apply a Policy in Connected Mode]. 
+
+=== Update Policies in Connected Mode
+
+To update a custom policy in API Manager:
+
+. Go to *Anypoint Platform > API Manager*.
+. In *API Administration* click the name of the API to which to apply a policy.
+. From the left navigation menu, click *Policies*.
+. Click the more options button (image:more-options-menu.png[1%,1%]) of the policy you want to update, and then click *Edit configuration*.
+. Select the *latest* version for *Policy version* configuration parameter.
+. Click *Save*.
+. Click the more options button (image:more-options-menu.png[1%,1%]) of the policy you want to update, and then click *Check for implementation updates*.
++
+For more information about implementation updates, see xref:exchange::manage-versions.adoc#update-policy-implementations[Update Policy Implementations].
+. In the confirmation dialog box, click *Update all*.
+
+
+
+[[apply-policies-in-local-mode]]
+== Apply Policies in Local Mode
+
+For Flex Gateway running in Local Mode, you apply custom policies using xref:gateway::flex-local-configuration-reference-guide.adoc[local declarative configuration files]. You specify the location of these configuration files when you first run Flex Gateway.
+
+To create the local declarative files:
+
+. In the `target/wasm32-wasi/release` PDK directory, copy both of the following files:
++
+* `<your_custom_policy>_definition.yaml`
+* `<your_custom_policy>_implementation.yaml`
++
+. Paste the two files in the `/etc/mulesoft/flex-gateway/conf.d/` Flex Gateway configuration directory.
++
+. Create a policy binding configuration file with a `.yaml` file extension to bind the policy to an API instance:
++
+* Give the file a custom name.
+* Save the file in the Flex Gateway configuration directory `/etc/mulesoft/flex-gateway/conf.d/custom`. This directory can contain multiple configuration files.
+. Copy and paste the following YAML snippet into the file, substituting your values where indicated:
++
+[source,yaml]
+----
+apiVersion: gateway.mulesoft.com/v1alpha1
+kind: PolicyBinding
+metadata:
+  name: <custom-policy-id>
+spec:
+  targetRef:
+    kind: ApiInstance
+    name: <your-api-instance>
+  policyRef:
+    kind: Extension
+    name: <your_custom_policy>-<version>-impl
+  config:
+    <custom-cofiguration-parameters>: "your parameter"
+----
++
+* `metadata.name`: The custom policy instance name.
+* `spec.targetRef.name`: The name of the API instance of which to apply the custom policy. The API instance must already have been defined and applied.
+* `spec.policyRef.name`: The custom policy implementation ID. To get the policy ID, run the `make show-policy-ref-name` command from the policy's root directory.
+* `spec.config`: Your policy configuration data.
++
+. Save the file. The gateway automatically refreshes the configuration.
+
+=== Update Policies in Local Mode
+
+To update a custom policy for Flex Gateway running in Local Mode:
+
+* If you did not edit the configuration parameters, replace your old `<your_custom_policy>_implementation.yaml` in your Flex Gateway configuration directory with the implementation file from your `target/wasm32-wasi/release` PDK directory.
+* If you did edit the configuration parameters, repeat the steps in <<apply-policies-in-local-mode>> to update your configuration parameters.
+
+== Reorder Custom Policies
+
+Reordering custom policies is the same as reordering included policies.
+
+To reorder policies, see xref:gateway::policies-reorder.adoc[].
+
+Polices execute in order on the request and then in inverse order on the response. However, some policies do not execute on both the request and the response.
+
+For example, policies ordered:
+
+. Policy X
+. Policy Y
+
+Execute Policy X then Policy Y on the request, and Policy Y then Policy X on the response.
+
+== See Also
+
+* xref:gateway::flex-local-configuration-reference-guide.adoc[]

pdk/1.3/modules/ROOT/pages/policies-pdk-architecture.adoc

@@ -0,0 +1,47 @@
+= Policy Development Kit Architecture Overview
+ifndef::env-site,env-github[]
+include::_attributes.adoc[]
+endif::[]
+:imagesdir: ../assets/images
+
+Flex Gateway Policy Development Kit (PDK) consists of:
+
+* <<anypoint-cli-pdk-plugin>>: Generates and distributes the policy to Exchange
+* <<policy-template>>: Scaffolds new custom policies
+* <<sdk-building-tools, SDK Building Tools>>: Simplifies the development process
+
+== Anypoint CLI PDK Plugin
+
+The Anypoint CLI PDK plugin creates the PDK project and uploads policy assets to Exchange (for Connected Mode only). After creating the project, PDK provides a simplified set of commands in a `Makefile` to complete all following development steps.
+
+== Policy Template
+
+PDK generates some simple scaffolding when creating the policy.
+
+All generated files contain the required information to properly compile the policy.
+
+For more information about the included files, see xref:policies-pdk-create-project.adoc#project-structure[Project Structure].
+
+== SDK Building Tools
+
+Flex Gateway is built on Envoy which requires developed policies to be compatible with the event-driven https://github.com/proxy-wasm/spec[proxy-wasm^] architecture. 
+
+`proxy-wasm`'s event-driven architecture requires users to manage the different events that handle a single request. This causes the following drawbacks that make developing and maintaining event-driven code costly:
+
+* High complexity of the code due to the coupling of business logic with the entry points 
+* Inability to modularize common logic which creates monolithic code
+* Verbose non-linear control flow that creates difficult function callbacks and error propagation
+
+PDK provides building tools that abstract the developer from the event-oriented coding approach by using reactor and executor patterns. PDK provides the developer a way to code each incoming request in a linear method that results in: 
+
+* Fewer compile and runtime errors from using methods in the incorrect context
+* Reduced learning curve
+* Improved debugging by minimizing call stacks
+* Reduced code duplication
+* Improved parameter injection
+* Reduced use of dynamic memory that decreases indeterminism and the need for custom memory management
+
+== See Also
+
+* xref:policies-pdk-prerequisites.adoc[]
+

pdk/1.3/modules/ROOT/pages/policies-pdk-compile-policies.adoc

@@ -0,0 +1,36 @@
+= Compiling Custom Policies
+ifndef::env-site,env-github[]
+include::_attributes.adoc[]
+endif::[]
+:imagesdir: ../assets/images
+
+Compile your custom policy to create the policies binary target files by using the `make build` command. You must compile your custom policy after every time you edit the policy's source code before you can deploy the policy to a Flex Gateway.
+
+== Before You Begin
+
+Ensure you have completed all the steps in xref:policies-pdk-create-project.adoc[].
+
+== Compile Using Build Command
+
+To compile the policy, run the `make build` command from the policy's root folder:
+
+[source,ssh]
+----
+make build
+----
+
+The `make build` command preforms the following actions:
+
+. Runs the `make build-asset-files` script
+. Runs the `make build` command to compile the policy to a `WebAssembly` binary file
+. Generates additional configuration files that are not generated by the `make build-asset-files` script and are required to execute the policy
+
+The `make build` command outputs the generated files to the `target` directories.
+
+You can execute the `make build` command as many times as necessary to generate compiled artifacts. You must compile the custom policy for your source code and configuration edits to be present in the compiled artifacts.
+
+== See Also
+
+* xref:policies-pdk-debug-local.adoc[]
+* xref:policies-pdk-apply-policies.adoc[]
+* xref:policies-pdk-troubleshooting.adoc[]

pdk/1.3/modules/ROOT/pages/policies-pdk-configure-features-authentication.adoc

@@ -0,0 +1,76 @@
+= Accessing Request Authentication Information
+ifndef::env-site,env-github[]
+include::_attributes.adoc[]
+endif::[]
+:imagesdir: ../assets/images
+
+The `Authentication` injectable provides an interface to:
+
+* Propagate authentication data for consumption by other policies.
+* Consume authentication data already set by another policy. 
+
+To share data, `Authentication` implements the `AuthenticationHandler` trait:
+
+[source,Rust]
+----
+pub trait AuthenticationHandler {
+    fn authentication(&self) -> Option<AuthenticationData>;
+    fn set_authentication(&self, authentication: Option<&AuthenticationData>);
+}
+----
+
+The `AuthenticationData` struct contains the following authentication data:
+
+[source,Rust]
+----
+pub struct AuthenticationData {
+    pub principal: Option<String>,
+    pub client_id: Option<String>,
+    pub client_name: Option<String>,
+    pub properties: Value,
+}
+----
+
+For example, the following code reads the `Authentication` data and modifies it by overriding the `client_id` and `client_name`:
+
+[source,Rust]
+----
+async fn request_filter(state: RequestState, authentication: Authentication) -> Flow<()> {
+    let state = state.into_headers_state().await;
+    let header_handler = state.handler();
+
+    let auth = authentication.authentication().unwrap_or_default();
+
+    let properties = auth.properties.as_object().cloned().unwrap_or_default();
+
+    let client_id = header_handler
+        .header("custom_client_id_header")
+        .unwrap_or_default();
+    let client_name = header_handler
+        .header("custom_client_name_header")
+        .unwrap_or_default();
+
+    let auth = AuthenticationData::new(
+        auth.principal,
+        Some(client_id),
+        Some(client_name),
+        properties
+    );
+
+    authentication.set_authentication(Some(&auth));
+
+    Flow::Continue(())
+}
+
+#[entrypoint]
+async fn configure(launcher: Launcher) -> Result<()> {
+    let filter = on_request(|rs, auth| request_filter(rs, auth));
+    launcher.launch(filter).await?;
+    Ok(())
+}
+
+----
+
+== See Also
+
+* xref:policies-pdk-configure-features-inject-parameters.adoc[]

pdk/1.3/modules/ROOT/pages/policies-pdk-configure-features-caching.adoc

@@ -0,0 +1,46 @@
+= Sharing Data Between Workers and Configuring Caching 
+ifndef::env-site,env-github[]
+include::_attributes.adoc[]
+endif::[]
+:imagesdir: ../assets/images
+
+NOTE: To view an example policy project that uses caching, see https://github.com/mulesoft/pdk-custom-policy-examples/blob/{template-policies-url-ver-var}/data-caching/README.md[Data Caching Policy Example^].
+
+Envoy spawns many workers to increase the policy's capability of handling requests. A single worker handles all the stages of a specific request, including outgoing connections and the response flow. This enables you to track internal status for a specific request, and to create a sequential execution flow despite the underlying event-driven implementation. 
+
+Each worker processes a single request at a given time. To share a global state in a specific worker, use a `RefCell` without any risk of concurrent modification.
+
+Use the provided `Cache` mechanism to create a shared global state for all workers.
+
+After injecting the cache builder, provide an ID for the cache and the maximum number of elements the cache can support. 
+
+The following example configures a cache that can hold ten elements:
+
+[source,Rust]
+----
+#[entrypoint]
+async fn configure(
+    launcher: Launcher,
+    cache_builder: CacheBuilder,
+) -> Result<()> {
+    let cache = cache_builder.new(String::from("caching")).max_entries(10);
+    ...
+----
+
+The cache has the following interface:
+
+[source,Rust]
+----
+pub trait Cache {
+    fn save(&self, key: &str, value: Vec<u8>) -> Result<(), CacheError>;
+    fn get(&self, key: &str) -> Option<Vec<u8>>;
+    fn delete(&self, key: &str) -> Option<Vec<u8>>;
+    fn purge(&self);
+}
+----
+
+IMPORTANT: Because different workers write to the cache concurrently, there is no guarantee that the value overwritten when saving the cache is the same as when it was retrieved.
+
+== See Also
+
+* xref:policies-pdk-configure-features.adoc[]