or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

api-definitions.mdcommand-handlers.mdconstants-configuration.mdgateway-flow-rules.mdindex.mdparameter-processing.mdsentinel-integration.md
tile.json

tessl/maven-com-alibaba-csp--sentinel-api-gateway-adapter-common

Common abstraction module for API gateway flow control in Sentinel providing GatewayFlowRule and ApiDefinition for gateway-specific traffic management.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
mavenpkg:maven/com.alibaba.csp/sentinel-api-gateway-adapter-common@1.8.x

To install, run

npx @tessl/cli install tessl/maven-com-alibaba-csp--sentinel-api-gateway-adapter-common@1.8.0

index.mddocs/

Sentinel API Gateway Adapter Common

Sentinel API Gateway Adapter Common provides essential abstractions and utilities for implementing flow control and traffic shaping in API gateway environments within the Alibaba Sentinel ecosystem. This library enables API gateways to implement sophisticated traffic management capabilities including rate limiting, circuit breaking, concurrency control, and parameter-based flow control with dynamic rule configuration.

Package Information

  • Package Name: sentinel-api-gateway-adapter-common
  • Package Type: maven
  • Group ID: com.alibaba.csp
  • Language: Java
  • Installation: Add to your Maven pom.xml:
<dependency>  
    <groupId>com.alibaba.csp</groupId>
    <artifactId>sentinel-api-gateway-adapter-common</artifactId>
    <version>1.8.8</version>
</dependency>

Core Imports

import com.alibaba.csp.sentinel.adapter.gateway.common.SentinelGatewayConstants;
import com.alibaba.csp.sentinel.adapter.gateway.common.api.ApiDefinition;
import com.alibaba.csp.sentinel.adapter.gateway.common.api.GatewayApiDefinitionManager;
import com.alibaba.csp.sentinel.adapter.gateway.common.rule.GatewayFlowRule;
import com.alibaba.csp.sentinel.adapter.gateway.common.rule.GatewayRuleManager;
import com.alibaba.csp.sentinel.adapter.gateway.common.param.RequestItemParser;
import com.alibaba.csp.sentinel.adapter.gateway.common.slot.GatewayFlowSlot;

Basic Usage

import com.alibaba.csp.sentinel.adapter.gateway.common.api.*;
import com.alibaba.csp.sentinel.adapter.gateway.common.rule.*;
import static com.alibaba.csp.sentinel.adapter.gateway.common.SentinelGatewayConstants.*;

// Define API groups with predicates
ApiDefinition userApi = new ApiDefinition("user-api")
    .setPredicateItems(Set.of(
        new ApiPathPredicateItem()
            .setPattern("/api/users/**")
            .setMatchStrategy(URL_MATCH_STRATEGY_PREFIX)
    ));

// Load API definitions
Set<ApiDefinition> apis = Set.of(userApi);
GatewayApiDefinitionManager.loadApiDefinitions(apis);

// Create flow control rules
GatewayFlowRule flowRule = new GatewayFlowRule("user-api")
    .setResourceMode(RESOURCE_MODE_CUSTOM_API_NAME)
    .setGrade(FLOW_GRADE_QPS)
    .setCount(100)  // 100 QPS limit
    .setIntervalSec(1);

// Load gateway rules
Set<GatewayFlowRule> rules = Set.of(flowRule);
GatewayRuleManager.loadRules(rules);

Architecture

Sentinel API Gateway Adapter Common is built around several key components:

  • Constants System: SentinelGatewayConstants defining strategies and modes for gateway behavior
  • API Definition Management: ApiDefinition and GatewayApiDefinitionManager for defining and managing API groups with flexible predicates
  • Rule Management: GatewayFlowRule and GatewayRuleManager for flow control configuration with automatic conversion to core Sentinel rules
  • Parameter Parsing: RequestItemParser interface and implementations for extracting parameters from gateway requests
  • Sentinel Integration: GatewayFlowSlot providing flow control slot integration with Sentinel's processing chain
  • Command Interface: REST-like handlers for dynamic rule and API definition management

Capabilities

API Definition System

Flexible system for defining and managing gateway API groups using predicates. Supports path-based matching with exact, prefix, and regex strategies.

class ApiDefinition {
    ApiDefinition();
    ApiDefinition(String apiName);
    String getApiName();
    ApiDefinition setApiName(String apiName);
    Set<ApiPredicateItem> getPredicateItems();
    ApiDefinition setPredicateItems(Set<ApiPredicateItem> predicateItems);
}

class GatewayApiDefinitionManager {
    static void register2Property(SentinelProperty<Set<ApiDefinition>> property);
    static boolean loadApiDefinitions(Set<ApiDefinition> apiDefinitions);
    static ApiDefinition getApiDefinition(String apiName);
    static Set<ApiDefinition> getApiDefinitions();
    static boolean isValidApi(ApiDefinition apiDefinition);
}

API Definition System

Gateway Flow Rules

Comprehensive flow control rule system supporting QPS/thread-based limiting, burst control, and parameter-based flow control with automatic conversion to Sentinel core rules.

class GatewayFlowRule {
    GatewayFlowRule();
    GatewayFlowRule(String resource);
    String getResource();
    GatewayFlowRule setResource(String resource);
    int getResourceMode();
    GatewayFlowRule setResourceMode(int resourceMode);
    int getGrade();
    GatewayFlowRule setGrade(int grade);
    double getCount();
    GatewayFlowRule setCount(double count);
    long getIntervalSec();
    GatewayFlowRule setIntervalSec(long intervalSec);
    int getControlBehavior();
    GatewayFlowRule setControlBehavior(int controlBehavior);
    GatewayParamFlowItem getParamItem();
    GatewayFlowRule setParamItem(GatewayParamFlowItem paramItem);
}

class GatewayRuleManager {
    static void register2Property(SentinelProperty<Set<GatewayFlowRule>> property);
    static boolean loadRules(Set<GatewayFlowRule> rules);
    static Set<GatewayFlowRule> getRules();
    static Set<GatewayFlowRule> getRulesForResource(String resourceName);
    static boolean isValidRule(GatewayFlowRule rule);
}

Gateway Flow Rules

Parameter Processing

System for extracting and processing parameters from gateway requests for parameter-based flow control. Supports client IP, headers, URL parameters, and cookies.

interface RequestItemParser<T> {
    String getPath(T request);
    String getRemoteAddress(T request);
    String getHeader(T request, String key);
    String getUrlParam(T request, String paramName);
    String getCookieValue(T request, String cookieName);
}

class GatewayParamParser<T> {
    GatewayParamParser(RequestItemParser<T> requestItemParser);
    Object[] parseParameterFor(String resource, T request, Predicate<GatewayFlowRule> rulePredicate);
}

Parameter Processing

Sentinel Integration

Integration components for embedding gateway flow control into Sentinel's processing chain with slot-based architecture.

@Spi(order = -4000)
class GatewayFlowSlot extends AbstractLinkedProcessorSlot<DefaultNode> {
    void entry(Context context, ResourceWrapper resource, DefaultNode node, 
               int count, boolean prioritized, Object... args) throws Throwable;
    void exit(Context context, ResourceWrapper resourceWrapper, int count, Object... args);
}

Sentinel Integration

Command Handlers

REST-like command handlers for dynamic management of gateway rules and API definitions through Sentinel's command system.

@CommandMapping(name = "gateway/getRules", desc = "Fetch all gateway rules")
class GetGatewayRuleCommandHandler implements CommandHandler<String> {
    CommandResponse<String> handle(CommandRequest request);
}

@CommandMapping(name = "gateway/updateRules", desc = "Update gateway rules")  
class UpdateGatewayRuleCommandHandler implements CommandHandler<String> {
    CommandResponse<String> handle(CommandRequest request);
    WritableDataSource<Set<GatewayFlowRule>> getWritableDataSource();
    void setWritableDataSource(WritableDataSource<Set<GatewayFlowRule>> gatewayFlowWds);
}

Command Handlers

Constants and Configuration

class SentinelGatewayConstants {
    // Application type
    static final int APP_TYPE_GATEWAY = 1;
    
    // Resource modes
    static final int RESOURCE_MODE_ROUTE_ID = 0;
    static final int RESOURCE_MODE_CUSTOM_API_NAME = 1;
    
    // Parameter parse strategies
    static final int PARAM_PARSE_STRATEGY_CLIENT_IP = 0;
    static final int PARAM_PARSE_STRATEGY_HOST = 1;
    static final int PARAM_PARSE_STRATEGY_HEADER = 2;
    static final int PARAM_PARSE_STRATEGY_URL_PARAM = 3;
    static final int PARAM_PARSE_STRATEGY_COOKIE = 4;
    
    // URL matching strategies
    static final int URL_MATCH_STRATEGY_EXACT = 0;
    static final int URL_MATCH_STRATEGY_PREFIX = 1;
    static final int URL_MATCH_STRATEGY_REGEX = 2;
    
    // Parameter matching strategies
    static final int PARAM_MATCH_STRATEGY_EXACT = 0;
    static final int PARAM_MATCH_STRATEGY_PREFIX = 1;
    static final int PARAM_MATCH_STRATEGY_REGEX = 2;
    static final int PARAM_MATCH_STRATEGY_CONTAINS = 3;
}

Constants and Configuration