<!-- vale off --> <!-- markdownlint-disable --> <p align="center"> <img src="docs/content/assets/img/aperture_logo.png" alt="FluxNinja Aperture" width="75%"> <br/> <a href="https://docs.fluxninja.com"> <img alt="Documentation Reference" src="https://img.shields.io/badge/documentation-reference-brightgreen?style=for-the-badge&logo=data:image/png;base64,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"> </a> <a href="https://join.slack.com/t/fluxninja-aperture/shared_invite/zt-1eunlrkhh-10P1HUkmBfVJX3qrSLRk~g"> <img alt="Slack Community" src="https://img.shields.io/badge/Join%20Our%20Community-Slack-brightgreen?style=for-the-badge&logo=slack"> </a> <a href="https://dl.circleci.com/status-badge/img/gh/fluxninja/aperture/tree/main.svg?style=svg"> <img alt="Build Status" src="https://img.shields.io/circleci/build/github/fluxninja/aperture/main?style=for-the-badge&logo=circleci"> </a> <a href="https://goreportcard.com/report/github.com/fluxninja/aperture"> <img alt="Go Report Card" src="https://goreportcard.com/badge/github.com/fluxninja/aperture?style=for-the-badge"> </a> <a href="https://pkg.go.dev/github.com/fluxninja/aperture"> <img alt="Godoc Reference" src="https://img.shields.io/badge/godoc-reference-brightgreen?style=for-the-badge&logo=go&logoColor=white"> </a> </p> <!-- markdownlint-enable --> <!-- vale on -->

🥷 FluxNinja Aperture

Aperture is a distributed load management platform designed for rate limiting, caching, and prioritizing requests in cloud applications. Built upon a foundation of distributed counters, observability, and a global control plane, it provides a comprehensive suite of load management capabilities. These capabilities enhance the reliability and performance of cloud applications, while also optimizing cost and resource utilization.

Integrating Aperture in your application through SDKs is a simple 3-step process:

• Define labels: Define labels to identify users, entities, or features within your application. For example, you can define labels to identify individual users, features, or API endpoints.

<!-- vale off --> <!-- markdownlint-disable --> <details> <summary>Example</summary>

// Tailor policies to get deeper insights into your workload with labels that
// capture business context.
const labels = {
  // You can rate limit each user individually.
  user: "jack",
  // And have different rate limits for different tiers of users.
  tier: "premium",
  // You can also provide the tokens for each request.
  // Tokens are flexible: LLM AI tokens in a prompt, complexity of a request,
  // number of sub-actions, etc.
  tokens: "200",
  // When peak load exceeds external quotas or infrastructure capacity,
  // requests can be throttled and prioritized.
  priority: HIGH,
  // Get deep insights into your workload. You can slice and dice performance
  // metrics by any label.
  workload: "/chat",
};

<!-- markdownlint-enable --> <!-- vale on --> </details>

• Wrap your workload: Wrap your workload with startFlow and endFlow calls to establish control points around specific features or code sections inside your application. For example, you can wrap your API endpoints with Aperture SDKs to limit the number of requests per user or feature.

<!-- vale off --> <!-- markdownlint-disable --> <details> <summary>Example</summary>

// Wrap your workload with startFlow and endFlow calls, passing in the
// labels you defined earlier.
const flow = await apertureClient.startFlow("your_workload", {
  labels: labels,
  // Lookup result cache key to retrieve a cached result.
  resultCacheKey: queryParams,
});

// If rate or quota limit is not exceeded, the workload is executed.
if (flow.shouldRun()) {
  // Return a cached result or execute the workload.
  const cachedResult = flow.resultCache();
  const result = await yourWorkload(cachedResult);
  flow.setResultCache({
    value: result,
    ttl: { seconds: 86400, nanos: 0 },
  });
}
//

</details> <!-- markdownlint-enable --> <!-- vale on -->

• Configure & monitor policies: Configure policies to control the rate, concurrency, and priority of requests.

<!-- vale off --> <!-- markdownlint-disable --> <details> <summary>Policy YAML</summary>

blueprint: rate-limiting/base
uri: github.com/fluxninja/aperture/blueprints@latest
policy:
  policy_name: rate_limit
  rate_limiter:
    bucket_capacity: 60
    fill_amount: 60
    parameters:
      interval: 3600s
      limit_by_label_key: user
    selectors:
      - control_point: your_workload
        label_matcher:
          match_list:
            - key: tier
              operator: In
              values:
                - premium

</details> <!-- markdownlint-enable --> <!-- vale on -->

In addition to language SDKs, Aperture also integrates with existing control points such as API gateways, service meshes, and application middlewares.

⚙️ Load management capabilities

• ⏱️ Global Rate and Concurrency Limiting: Safeguard APIs and features against excessive usage with Aperture's high-performance, distributed rate limiter. Identify individual users or entities by fine-grained labels. Create precise rate limiters controlling burst-capacity and fill-rate tailored to business-specific labels. Limit per user or global concurrency of in-flight requests. Refer to the Rate Limiting and Concurrency Limiting guides for more details.
• 📊 API Quota Management: Maintain compliance with external API quotas with a global token bucket and smart request queuing. This feature regulates requests aimed at external services, ensuring that the usage remains within prescribed rate limits and avoids penalties or additional costs. Refer to the API Quota Management guide for more details.
• 🚦 Concurrency Control and Prioritization: Safeguard against abrupt service overloads by limiting the number of concurrent in-flight requests. Any requests beyond