From 96947cac41254d1fe6854ae5f8f99bbf3f488e50 Mon Sep 17 00:00:00 2001 From: Karanbir Sohi Date: Tue, 30 Jan 2024 11:22:39 +0530 Subject: [PATCH 1/3] Update each SDK readme with code examples --- sdks/aperture-csharp/README.md | 68 +++++++++++++++++++++++++++- sdks/aperture-go/README.md | 5 ++- sdks/aperture-java/README.md | 81 +++++++++++++++++++++++++++++++++- sdks/aperture-js/README.md | 56 +++++++++++++++++++++-- sdks/aperture-py/README.md | 72 ++++++++++++++++++++++++++++-- 5 files changed, 272 insertions(+), 10 deletions(-) diff --git a/sdks/aperture-csharp/README.md b/sdks/aperture-csharp/README.md index c7f895c8fc..cef067d62f 100644 --- a/sdks/aperture-csharp/README.md +++ b/sdks/aperture-csharp/README.md @@ -14,5 +14,71 @@ # C# SDK for FluxNinja Aperture -C# SDK provides an easy way to integrate your .NET applications with +The C# SDK provides an easy way to integrate your .NET applications with [FluxNinja Aperture](https://github.com/fluxninja/aperture). + +## Usage + +### Install + +```bash +dotnet add package ApertureSDK --version 2.23.1 +``` + +### Create Aperture Client + +```csharp +var sdk = ApertureSdk + .Builder() + .SetAddress("ORGANIZATION.app.fluxninja.com:443") + .SetAgentApiKey("API_KEY") + .Build(); +``` + +### Flow Functionality + +```csharp +// do some business logic to collect labels +var labels = new Dictionary(); +labels.Add("userId", "some_user_id"); +labels.Add("userTier", "gold"); +labels.Add("priority", "100"); + +var rampMode = false; +var flowTimeout = TimeSpan.FromSeconds(5); +var pms = new FeatureFlowParams( + "featureName", + labels, + rampMode, + flowTimeout, + new Grpc.Core.CallOptions(), + "test", + new RepeatedField { "test" }); + +var flow = sdk.StartFlow(pms); + +if (flow.ShouldRun()) +{ + // do actual work + Thread.Sleep(2000); + SimpleHandlePath((int)HttpStatusCode.OK, "Hello world!", response); +} +else +{ + // handle flow rejection by Aperture Agent + flow.SetStatus(FlowStatus.Error); + SimpleHandlePath(flow.GetRejectionHttpStatusCode(), "REJECTED!", response); +} + +var endResponse = flow.End(); +if (endResponse.Error != null) +{ + // handle end failure + log.Error("Failed to end flow: {e}", endResponse.Error); +} +else if (endResponse.FlowEndResponse != null) +{ + // handle end success + log.Info("Ended flow with response: " + endResponse.FlowEndResponse.ToString()); +} +``` diff --git a/sdks/aperture-go/README.md b/sdks/aperture-go/README.md index ad6cb5aa78..4c3825f809 100644 --- a/sdks/aperture-go/README.md +++ b/sdks/aperture-go/README.md @@ -1,7 +1,8 @@ # Aperture-Go SDK -`aperture-go` is an SDK to interact with Aperture Agent. It allows flow control -functionality on fine-grained features inside service code. +The `aperture-go` SDK provides an easy way to integrate your go applications +with [FluxNinja Aperture](https://github.com/fluxninja/aperture). It allows flow +control functionality on fine-grained features inside service code. ## Usage diff --git a/sdks/aperture-java/README.md b/sdks/aperture-java/README.md index e3b2dfedac..de61162024 100644 --- a/sdks/aperture-java/README.md +++ b/sdks/aperture-java/README.md @@ -17,5 +17,84 @@ # Java SDK for FluxNinja Aperture -Java SDK provides an easy way to integrate your Java applications with +The Java SDK provides an easy way to integrate your Java applications with [FluxNinja Aperture](https://github.com/fluxninja/aperture). + +## Usage + +Follow this +[link](https://central.sonatype.com/artifact/com.fluxninja.aperture/aperture-java-core?smo=true) +to install the Aperture Java SDK. + +### Create Aperture Client + +```java +import com.fluxninja.aperture.sdk.ApertureSDK; +import com.fluxninja.aperture.sdk.EndResponse; +import com.fluxninja.aperture.sdk.FeatureFlowParameters; +import com.fluxninja.aperture.sdk.Flow; +import com.fluxninja.aperture.sdk.FlowStatus; + + String agentAddress = "ORGANIZATION.app.fluxninja.com:443"; + String apiKey = "API_KEY"; + + ApertureSDK apertureSDK; + try { + apertureSDK = + ApertureSDK.builder() + .setAddress(agentAddress) + .setAPIKey(apiKey) + .useInsecureGrpc(insecureGrpc) + .setRootCertificateFile(rootCertFile) + .build(); + } catch (IOException e) { + e.printStackTrace(); + return; + } +``` + +### Flow Functionality + +```java +Map labels = new HashMap<>(); + +// business logic produces labels +labels.put("userId", "some_user_id"); +labels.put("userTier", "gold"); +labels.put("priority", "100"); + +Boolean rampMode = false; + +FeatureFlowParameters params = + FeatureFlowParameters.newBuilder("featureName") + .setExplicitLabels(labels) + .setRampMode(rampMode) + .setFlowTimeout(Duration.ofMillis(1000)) + .build(); +// StartFlow performs a flowcontrolv1.Check call to Aperture. It returns a Flow. +Flow flow = this.apertureSDK.startFlow(params); + +// See whether flow was accepted by Aperture. +try { + if (flow.shouldRun()) { + // do actual work + res.status(202); + } else { + // handle flow rejection by Aperture + res.status(flow.getRejectionHttpStatusCode()); + } +} catch (Exception e) { + // Flow Status captures whether the feature captured by the Flow was + // successful or resulted in an error. When not explicitly set, + // the default value is FlowStatus.OK . + flow.setStatus(FlowStatus.Error); + logger.error("Error in flow execution", e); +} finally { + EndResponse endResponse = flow.end(); + if (endResponse.getError() != null) { + logger.error("Error ending flow", endResponse.getError()); + } + + logger.info("Flow End response: {}", endResponse.getFlowEndResponse()); +} +``` diff --git a/sdks/aperture-js/README.md b/sdks/aperture-js/README.md index edadfdeaa2..f064de9347 100644 --- a/sdks/aperture-js/README.md +++ b/sdks/aperture-js/README.md @@ -14,9 +14,9 @@ # Aperture JavaScript SDK -`aperture-js` is an SDK to interact with [Aperture](https://docs.fluxninja.com) -Agent. It allows flow control functionality on fine-grained features inside -service code. +The `aperture-js` SDK provides an easy to way to integrate your js applications +with [FluxNinja Aperture](https://github.com/fluxninja/aperture). It allows flow +control functionality on fine-grained features inside service code. Refer [documentation](https://docs.fluxninja.com/sdk/javascript/) for more details. @@ -44,3 +44,53 @@ details. - [KeyDeleteResponse](docs/interfaces/KeyDeleteResponse.md) - [KeyLookupResponse](docs/interfaces/KeyLookupResponse.md) - [KeyUpsertResponse](docs/interfaces/KeyUpsertResponse.md) + +## Usage + +### Install SDK + +```bash +npm install @fluxninja/aperture-js +``` + +### Create Aperture Client + +```typescript +import { ApertureClient } from "@fluxninja/aperture-js"; + +// Create aperture client +export const apertureClient = new ApertureClient({ + address: "ORGANIZATION.app.fluxninja.com:443", + apiKey: "API_KEY", +}); +``` + +### Flow Functionality + +```typescript +async function handleRequestRateLimit(req: Request, res: Response) { + // Start a flow by passing control point and business labels + const flow = await apertureClient.startFlow("awesomeFeature", { + labels: { + limit_key: "some_user_id", + }, + grpcCallOptions: { + deadline: Date.now() + 300, // ms + }, + }); + + if (flow.shouldRun()) { + // Add business logic to process incoming request + console.log("Request accepted. Processing..."); + const resString = "foo"; + res.send({ message: resString }); + } else { + console.log("Request rate-limited. Try again later."); + // Handle flow rejection + flow.setStatus(FlowStatus.Error); + res.status(429).send({ message: "Too many requests" }); + } + + flow.end(); +} +``` diff --git a/sdks/aperture-py/README.md b/sdks/aperture-py/README.md index 8b18afa1bc..fe3d019f6e 100644 --- a/sdks/aperture-py/README.md +++ b/sdks/aperture-py/README.md @@ -11,9 +11,75 @@ # Aperture Python SDK -`aperture-py` is an SDK to interact with [Aperture](https://docs.fluxninja.com) -Agent. It allows flow control functionality on fine-grained features inside -service code. +The `aperture-py` is SDK is an easy way to integrate your python applications +with [FluxNinja Aperture](https://github.com/fluxninja/aperture). It allows flow +control functionality on fine-grained features inside service code. Refer to [documentation](https://docs.fluxninja.com/sdk/python/) for more details. + +## Usage + +### Install SDK + +```bash +pip install aperture-py +``` + +### Create Aperture Client + +```python +from aperture_sdk.client import ApertureClient, FlowParams + + +agent_address = os.getenv("APERTURE_AGENT_ADDRESS", default_agent_address) +api_key = os.getenv("APERTURE_API_KEY", "") +insecure = os.getenv("APERTURE_AGENT_INSECURE", "true").lower() == "true" + +aperture_client = ApertureClient.new_client( + address=agent_address, insecure=insecure, api_key=api_key +) +``` + +### Flow Functionality + +```python +# business logic produces labels + labels = { + "user_id": "some_user_id", + "user_tier": "gold", + "priority": "100", + } + flow_params = FlowParams( + check_timeout=timedelta(seconds=200), + explicit_labels=labels, + ) + # start_flow performs a flowcontrol.v1.Check call to Aperture Agent. + # It returns a Flow or raises an error if any. + flow = await aperture_client.start_flow( + control_point="AwesomeFeature", + params=flow_params, + ) + + # Check if flow check was successful. + if not flow.success: + logger.info("Flow check failed - will fail-open") + + # See whether flow was accepted by Aperture Agent. + if flow.should_run(): + # do actual work + pass + else: + # handle flow rejection by Aperture Agent + flow.set_status(FlowStatus.Error) + + res = await flow.end() + if res.get_error(): + logger.error("Error: {}".format(res.get_error())) + elif res.get_flow_end_response(): + logger.info("Flow End Response: {}".format(res.get_flow_end_response())) + + # Simulate work being done + await asyncio.sleep(2) + return "", 202 +``` From 9be5fdf98a6cf35d5c88127d3f740e0b3944ca5a Mon Sep 17 00:00:00 2001 From: Karanbir Sohi Date: Tue, 30 Jan 2024 12:22:39 +0530 Subject: [PATCH 2/3] Fix typos --- sdks/aperture-csharp/README.md | 21 +++++++++++++++++++++ sdks/aperture-go/README.md | 7 +++++++ sdks/aperture-java/README.md | 19 +++++++++++++++++++ sdks/aperture-js/README.md | 31 ++++++++++++++++++++++++++++--- sdks/aperture-py/README.md | 20 +++++++++++++++++++- 5 files changed, 94 insertions(+), 4 deletions(-) diff --git a/sdks/aperture-csharp/README.md b/sdks/aperture-csharp/README.md index cef067d62f..efc9402b78 100644 --- a/sdks/aperture-csharp/README.md +++ b/sdks/aperture-csharp/README.md @@ -21,12 +21,19 @@ The C# SDK provides an easy way to integrate your .NET applications with ### Install +Run the command below to install the SDK: + ```bash dotnet add package ApertureSDK --version 2.23.1 ``` ### Create Aperture Client +The next step is to create an Aperture Client instance, for which, the address +of the organization created in Aperture Cloud and API key are needed. You can +locate both these details by clicking on the Aperture tab in the sidebar menu of +Aperture Cloud. + ```csharp var sdk = ApertureSdk .Builder() @@ -37,6 +44,8 @@ var sdk = ApertureSdk ### Flow Functionality +The created instance can then be used to start a flow: + ```csharp // do some business logic to collect labels var labels = new Dictionary(); @@ -82,3 +91,15 @@ else if (endResponse.FlowEndResponse != null) log.Info("Ended flow with response: " + endResponse.FlowEndResponse.ToString()); } ``` + +The above code snippet is making `StartFlow` calls to Aperture. For this call, +it is important to specify the control point (`featureName` in the example) and +business labels that will be aligned with the policy created in Aperture Cloud. +For request prioritization use cases, it's important to set a higher gRPC +deadline. This parameter specifies the maximum duration a request can remain in +the queue. For each flow that is started, a `ShouldRun` decision is made, +determining whether to allow the request into the system or to rate limit it. In +this example, we only see log returns, but in a production environment, actual +business logic can be executed when a request is allowed. It is important to +make the `End` call made after processing each request, to send telemetry data +that would provide granular visibility for each flow. diff --git a/sdks/aperture-go/README.md b/sdks/aperture-go/README.md index 4c3825f809..901e6283ef 100644 --- a/sdks/aperture-go/README.md +++ b/sdks/aperture-go/README.md @@ -6,12 +6,19 @@ control functionality on fine-grained features inside service code. ## Usage +Run the command below to install the SDK: + ```bash go get github.com/fluxninja/aperture-go/v2 ``` ### ApertureClient Interface +The next step is to create an Aperture Client instance, for which, the address +of the organization created in Aperture Cloud and API key are needed. You can +locate both these details by clicking on the Aperture tab in the sidebar menu of +Aperture Cloud. + `ApertureClient` maintains a gRPC connection with Aperture Agent. ```go diff --git a/sdks/aperture-java/README.md b/sdks/aperture-java/README.md index de61162024..3a17fc52d8 100644 --- a/sdks/aperture-java/README.md +++ b/sdks/aperture-java/README.md @@ -28,6 +28,11 @@ to install the Aperture Java SDK. ### Create Aperture Client +The next step is to create an Aperture Client instance, for which, the address +of the organization created in Aperture Cloud and API key are needed. You can +locate both these details by clicking on the Aperture tab in the sidebar menu of +Aperture Cloud. + ```java import com.fluxninja.aperture.sdk.ApertureSDK; import com.fluxninja.aperture.sdk.EndResponse; @@ -55,6 +60,8 @@ import com.fluxninja.aperture.sdk.FlowStatus; ### Flow Functionality +The created instance can then be used to start a flow: + ```java Map labels = new HashMap<>(); @@ -98,3 +105,15 @@ try { logger.info("Flow End response: {}", endResponse.getFlowEndResponse()); } ``` + +The above code snippet is making `startFlow` calls to Aperture. For this call, +it is important to specify the control point (`featureName` in the example) and +business labels that will be aligned with the policy created in Aperture Cloud. +For request prioritization use cases, it's important to set a higher gRPC +deadline. This parameter specifies the maximum duration a request can remain in +the queue. For each flow that is started, a `shouldRun` decision is made, +determining whether to allow the request into the system or to rate limit it. In +this example, we only see response returns, but in a production environment, +actual business logic can be executed when a request is allowed. It is important +to make the `end` call made after processing each request, to send telemetry +data that would provide granular visibility for each flow. diff --git a/sdks/aperture-js/README.md b/sdks/aperture-js/README.md index f064de9347..a956206a8c 100644 --- a/sdks/aperture-js/README.md +++ b/sdks/aperture-js/README.md @@ -14,9 +14,10 @@ # Aperture JavaScript SDK -The `aperture-js` SDK provides an easy to way to integrate your js applications -with [FluxNinja Aperture](https://github.com/fluxninja/aperture). It allows flow -control functionality on fine-grained features inside service code. +The `aperture-js` SDK provides an easy way to integrate your javascript +applications with [FluxNinja Aperture](https://github.com/fluxninja/aperture). +It allows flow control functionality on fine-grained features inside service +code. Refer [documentation](https://docs.fluxninja.com/sdk/javascript/) for more details. @@ -49,12 +50,19 @@ details. ### Install SDK +Run the command below to install the SDK: + ```bash npm install @fluxninja/aperture-js ``` ### Create Aperture Client +The next step is to create an Aperture Client instance, for which, the address +of the organization created in Aperture Cloud and API key are needed. You can +locate both these details by clicking on the Aperture tab in the sidebar menu of +Aperture Cloud. + ```typescript import { ApertureClient } from "@fluxninja/aperture-js"; @@ -67,6 +75,8 @@ export const apertureClient = new ApertureClient({ ### Flow Functionality +The created instance can then be used to start a flow: + ```typescript async function handleRequestRateLimit(req: Request, res: Response) { // Start a flow by passing control point and business labels @@ -94,3 +104,18 @@ async function handleRequestRateLimit(req: Request, res: Response) { flow.end(); } ``` + +The above code snippet is making `startFlow` calls to Aperture. For this call, +it is important to specify the control point (`awesomeFeature` in the example) +and business labels that will be aligned with the policy created in Aperture +Cloud. For request prioritization use cases, it's important to set a higher gRPC +deadline. This parameter specifies the maximum duration a request can remain in +the queue. For each flow that is started, a `shouldRun` decision is made, +determining whether to allow the request into the system or to rate limit it. In +this example, we only see log returns, but in a production environment, actual +business logic can be executed when a request is allowed. It is important to +make the `end` call made after processing each request, to send telemetry data +that would provide granular visibility for each flow. + +For more context on using the Aperture JavaScript SDK to set feature control +points, refer to the [example app][example] available in the repository. diff --git a/sdks/aperture-py/README.md b/sdks/aperture-py/README.md index fe3d019f6e..44a9ebb44b 100644 --- a/sdks/aperture-py/README.md +++ b/sdks/aperture-py/README.md @@ -22,16 +22,22 @@ details. ### Install SDK +Run the command below to install the SDK: + ```bash pip install aperture-py ``` ### Create Aperture Client +The next step is to create an Aperture Client instance, for which, the address +of the organization created in Aperture Cloud and API key are needed. You can +locate both these details by clicking on the Aperture tab in the sidebar menu of +Aperture Cloud. + ```python from aperture_sdk.client import ApertureClient, FlowParams - agent_address = os.getenv("APERTURE_AGENT_ADDRESS", default_agent_address) api_key = os.getenv("APERTURE_API_KEY", "") insecure = os.getenv("APERTURE_AGENT_INSECURE", "true").lower() == "true" @@ -43,6 +49,8 @@ aperture_client = ApertureClient.new_client( ### Flow Functionality +The created instance can then be used to start a flow: + ```python # business logic produces labels labels = { @@ -83,3 +91,13 @@ aperture_client = ApertureClient.new_client( await asyncio.sleep(2) return "", 202 ``` + +The above code snippet is making `start_flow` calls to Aperture. For this call, +it is important to specify the control point (`AwesomeFeature` in the example) +and `FlowParams` that will be aligned with the policy created in Aperture Cloud. +For request prioritization use cases, it's important to set a higher gRPC +deadline. This parameter specifies the maximum duration a request can remain in +the queue. For each flow that is started, a `should_run` decision is made, +determining whether to allow the request into the system or to rate limit it. It +is important to make the `end` call made after processing each request, to send +telemetry data that would provide granular visibility for each flow. From 0c260265bbeb1aac5a210a948301fd6497a88a8c Mon Sep 17 00:00:00 2001 From: Hardik Shingala Date: Tue, 30 Jan 2024 12:47:35 +0530 Subject: [PATCH 3/3] Sync SDK READMEs --- sdks/aperture-csharp/README.md | 8 ++++++-- sdks/aperture-go/README.md | 4 +++- sdks/aperture-java/README.md | 7 +++++-- sdks/aperture-js/README.md | 4 ++-- sdks/aperture-py/README.md | 4 ++-- 5 files changed, 18 insertions(+), 9 deletions(-) diff --git a/sdks/aperture-csharp/README.md b/sdks/aperture-csharp/README.md index efc9402b78..6e3c9dbbac 100644 --- a/sdks/aperture-csharp/README.md +++ b/sdks/aperture-csharp/README.md @@ -14,8 +14,12 @@ # C# SDK for FluxNinja Aperture -The C# SDK provides an easy way to integrate your .NET applications with -[FluxNinja Aperture](https://github.com/fluxninja/aperture). +The `aperture-csharp` SDK provides an easy way to integrate your .NET +applications with [FluxNinja Aperture](https://github.com/fluxninja/aperture). +It allows flow control functionality on fine-grained features inside service +code. + +Refer [documentation](https://docs.fluxninja.com/sdk/dotnet/) for more details. ## Usage diff --git a/sdks/aperture-go/README.md b/sdks/aperture-go/README.md index 901e6283ef..31c830e870 100644 --- a/sdks/aperture-go/README.md +++ b/sdks/aperture-go/README.md @@ -1,9 +1,11 @@ -# Aperture-Go SDK +# Go SDK for FluxNinja Aperture The `aperture-go` SDK provides an easy way to integrate your go applications with [FluxNinja Aperture](https://github.com/fluxninja/aperture). It allows flow control functionality on fine-grained features inside service code. +Refer [documentation](https://docs.fluxninja.com/sdk/go/) for more details. + ## Usage Run the command below to install the SDK: diff --git a/sdks/aperture-java/README.md b/sdks/aperture-java/README.md index 3a17fc52d8..68fcff121c 100644 --- a/sdks/aperture-java/README.md +++ b/sdks/aperture-java/README.md @@ -17,8 +17,11 @@ # Java SDK for FluxNinja Aperture -The Java SDK provides an easy way to integrate your Java applications with -[FluxNinja Aperture](https://github.com/fluxninja/aperture). +The `aperture-java` SDK provides an easy way to integrate your Java applications +with [FluxNinja Aperture](https://github.com/fluxninja/aperture). It allows flow +control functionality on fine-grained features inside service code. + +Refer [documentation](https://docs.fluxninja.com/sdk/java/) for more details. ## Usage diff --git a/sdks/aperture-js/README.md b/sdks/aperture-js/README.md index a956206a8c..c6dd79f0d0 100644 --- a/sdks/aperture-js/README.md +++ b/sdks/aperture-js/README.md @@ -12,9 +12,9 @@

-# Aperture JavaScript SDK +# JavaScript SDK for FluxNinja Aperture -The `aperture-js` SDK provides an easy way to integrate your javascript +The `aperture-js` SDK provides an easy way to integrate your JavaScript applications with [FluxNinja Aperture](https://github.com/fluxninja/aperture). It allows flow control functionality on fine-grained features inside service code. diff --git a/sdks/aperture-py/README.md b/sdks/aperture-py/README.md index 44a9ebb44b..5bb2213067 100644 --- a/sdks/aperture-py/README.md +++ b/sdks/aperture-py/README.md @@ -9,9 +9,9 @@

-# Aperture Python SDK +# Python SDK for FluxNinja Aperture -The `aperture-py` is SDK is an easy way to integrate your python applications +The `aperture-py` SDK provides an easy way to integrate your Python applications with [FluxNinja Aperture](https://github.com/fluxninja/aperture). It allows flow control functionality on fine-grained features inside service code.