Selector Detailed Explanation

Features

• Selector and rule are the key point of soul gateway, you can manage any request with it.

• This chapter is mainly focus on the concepts of selector and rule and how to use it.

Overview

• One plugin has many selector and a selector has many rules, selector is the first filter of request, and the rule is the final filter.
• Please consider this, it would be perfect when the plugin executes the request until it reached the config value.
• Selector and rule are designed to execute only when the request meet the specific condition.
• Please refer to the previous data structure database design.

Selector

• selector detailed explanation：

  • name：create your selector with a distinguish name.
  • type：custom flow is customized request, full flow is full request. customized request will be handled by the conditions as below, while full request won't.
  • match method: you can combine these conditions with 'and' , 'or' operators.
  • condition：
    • uri: filter request with uri method and support fuzzy matching (/**).
    • header: filter request with request header.
    • query: filter request with query string.
    • ip: filter request with your real ip.
    • host: filter request with your real host.
    • post: not recommend to use.
    • condition match:
      • match : fuzzy string matching，recommend to combine with uri，support restful matching.（/test/**).
      • = : if the values are the same, then they match.
      • regEx : regex matching，match characters in regex expression.
      • like : string fuzzy matching.
  • open option：only work with enabled.
  • print log：it will print the matching log with the open option enabled.
  • execution order：the smaller will have high priorty to execute among multi-selectors.

• the above picture means: when the prefix of the request uri is /test and the value of module inheader istest, it will redirect to this service 1.1.1.1:8080.

• selector advice : combine uri conditon and match prefix（/contextPath）as the first request filter.

Rule

• when the request was passed by the seletor, then it will be processed by the rule, the final filter.

• rule is the final confirmation about how to execute request logically.

• rule detailed explanation：

  • name：create your rule with a distinguish name.
  • match method: you can combine these conditions with 'and' , 'or' operators.
  • condition：
    • uri: filter request with uri method and support fuzzy matching (/**).
    • header: filter request with request header.
    • query: filter request with query string.
    • ip: filter request with your real ip.
    • host: filter request with your real host.
    • post: not recommend to use.
    • condition match:
      • match : fuzzy string matching，recommend to combine with uri，support restful matching.（/test/**）
      • = : if the values are the same, then they match.
      • regEx : regex matching，match characters in regex expression.
      • like : string fuzzy matching.
  • open option：only work with enabled.
  • print log：it will print the matching log with the open option enabled.
  • execution order：the smaller will have high priorty to execute among multi-rules.
  • handle: different plugin has different execution method, pls refer to the specific one.

• above picture means: when the request uri equals to /http/order/save, it will execute based on this rule，load strategy is random.

• combine selector means ：when the request uri is /http/order/save, it will be redicted to 1.1.1.1:8080 by random method.

• rule advice: combine uri condition with match the real uri path condition as the final filter.

Condition Explanation

• uri matching （recommend）

  • uri matching is based on your request uri, the frontend won't change anything before accessing the gateway.

  • the match filter method is the same withspringmvc fuzzy matching.

  • in selector，we recommend to match with the prefix of uri, and use the specific path in rule.

  • when changing the match method, the matching field name can be filled randomly, but make sure the match value must be correct.

• header matching

  • header matches with your http request header value.

• query matching

  • it matches the query string in your uri, such as: /test?a=1&&b=2.

  • so you can add a new condition, choose query method: a = 1.

• ip matching

  • it matches the ip of the http caller.

  • especially in the waf plugin, if you find some ip is unsafe, you can add a match condition with this ip, then it can't access any more.

  • if you use nginx proxy before soul, you can get the right ip with refering to parsing-ip-and-host

• host matching

  • it matches the host of http caller.

  • especially in waf plugin, if you find some host is unsafe, you can add a match condition with this host, then it can't access any more.

  • if you use nginx proxy before soul, you can get the right ip with refering to parsing-ip-and-host

• post matching

  • not recommend to use.