# rule

## Summary

Rules dictate logic on traffic is routed. Attributes from incoming requests are matched against preconfigured `rule` objects to determine where the outgoing upstream request should be routed. Rules are specified programmatically in [`routes`](https://greymatter.gitbook.io/grey-matter-documentation/1.3/reference/api/fabric-api/route) and [`shared_rules`](https://greymatter.gitbook.io/grey-matter-documentation/1.3/reference/api/fabric-api/shared_rules) as an array in the `Rules` attribute.

### Example object

```javascript
{
  "rule_key": "rkey1",
  "methods": [
    "GET"
  ],
  "matches": [
    {
      "kind": "header",
      "from": {
        "key": "routeTo",
        "value": "passthrough-cluster"
      }
    }
  ],
  "constraints": {
    "light": [
      {
        "cluster_key": "passthrough-cluster",
        "weight": 1
      }
    ]
  }
}
```

### Fields

#### `rule_key`

A unique key for each rule. When a request is routed by a rule, it appends the header `"X-Gm-Rule"` with the rule key.

#### `methods`

The supported request methods for this rule. Setting to an empty array will allow all methods.

#### `matches`

[Matches](https://greymatter.gitbook.io/grey-matter-documentation/1.3/reference/api/fabric-api/route/match) for this rule.

#### `constraints`

The `constraints` field defines [cluster\_constraint](https://greymatter.gitbook.io/grey-matter-documentation/1.3/reference/api/fabric-api/shared_rules/cluster_constraint) arrays that map requests to clusters. Currently, the only implemented field is the `light` field which is used to determine the Instance to which the live request will be sent and from which the response will be sent to the caller.

Currently, the `constraints` field must set a `light` field that contains an array of [cluster\_constraints](https://greymatter.gitbook.io/grey-matter-documentation/1.3/reference/api/fabric-api/shared_rules/cluster_constraint).

```javascript
"constraints" : {
  "light": [
    {
      "cluster_key": "example-service-1.0",
      "weight": 10
    },
    {
      "cluster_key": "example-service-1.1",
      "weight": 1
    }
  ]
}
```

> NOTE: `constraints` also contains a `dark` and a `light` field which currently have no effect. `dark` array will be used in future versions to support traffic shadowing to Instances. Similarly the `tap` array will determine an Instance to send a copy of the request to, comparing the response to the `light` response.

#### `cohort_seed`

This field has no effect.