# 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.7-beta/reference/api/fabric-api/route) and [`shared_rules`](https://greymatter.gitbook.io/grey-matter-documentation/1.7-beta/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.7-beta/reference/api/fabric-api/route/match) for this rule.

#### `constraints`

The `constraints` field defines [cluster\_constraint](https://greymatter.gitbook.io/grey-matter-documentation/1.7-beta/reference/api/fabric-api/shared_rules/cluster_constraint) arrays that map requests to clusters. These fall into two categories: `light` and `dark`.

**light**

The `light` field determines the "live" or "primary" traffic to/from the clusters. Responses from these requests are returned 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.7-beta/reference/api/fabric-api/shared_rules/rule).

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

**dark**

The `dark` field determines the "shadow" traffic to send to a cluster. The responses from this traffic will never be returned to the caller. This traffic can be used to do test deployments of new clusters, or to tap traffic for monitoring/audit purposes without worrying about the affect on the user.

The below example would shadow 50% of the traffic from the 1.0 cluster to the 2.0 cluster. Note that `weight` is interpreted as a percentage from 0-100 when used in the `dark` constraint.

```javascript
"constraints" : {
  "light": [
    {
      "cluster_key": "example-service-1.0",
      "weight": 1
    }
  ],
  "dark": [
    {
      "cluster_key": "example-service-2.0",
      "weight": 50
    }
  ]
}
```

#### `cohort_seed`

This field has no effect.