@takodotid/circuit 0.7.0 → 0.9.0

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@takodotid/circuit",
-    "version": "0.7.0",
+    "version": "0.9.0",
     "description": "Declarative, vendor-neutral network configuration: describe each device in TypeScript, and Circuit makes the device match. Alpha.",
     "keywords": [
         "network",

package/src/adapters/devices/routeros/TRAPS.md

@@ -31,3 +31,5 @@ Behaviour that looks like something else. Each one has been hit on a real device
 - `:find` on an array returns a number or `nil`. Globals persist between exec commands of one login.
 - A fixed port speed is named by medium, `speed=10G-baseSR-LR` for an optic or `speed=1G-baseT-full` for copper, and only holds with `auto-negotiation=no`. With auto-negotiation back on, the export no longer prints the speed, so the plan resets only auto-negotiation. `speed=""` is refused as ambiguous and `unset speed` does not exist.
 - `bgp-path-len` counts every AS in the path, prepends included, and takes the same strict comparisons as `dst-len`.
+- `:parse` checks the command, not the text inside `rule=`. A routing filter rule is only checked when it is added.
+- `/routing/filter/filter-wizard` adds the rule it builds; it is not a dry run. `set blackhole yes` was proved this way on 7.23, in an unused chain removed right after.

package/src/adapters/devices/routeros/render.ts

@@ -874,12 +874,13 @@ export const RPKI_GROUP = "rpki";
 /** The chain a session without a policy uses, so that it learns or announces nothing. */
 export const REJECT_ALL = "REJECT-ALL";
 
+// RouterOS takes our own role. The config states the neighbor's, so each becomes its opposite: a neighbor that is our provider makes us its customer.
 const ROLES = {
-    provider: "ebgp-provider",
-    customer: "ebgp-customer",
+    provider: "ebgp-customer",
+    customer: "ebgp-provider",
     peer: "ebgp-peer",
-    rs: "ebgp-rs",
-    "rs-client": "ebgp-rs-client",
+    rs: "ebgp-rs-client",
+    "rs-client": "ebgp-rs",
 } as const;
 
 type AnyRule = PolicyRule<string, string>;
@@ -1005,6 +1006,7 @@ function actions(rule: AnyRule, family: Family): string[] {
     // An address only means something to routes of its own family.
     if (set.next_hop && familyOf(set.next_hop) === family) steps.push(`set gw ${set.next_hop}`);
     if (set.preferred_source && familyOf(set.preferred_source) === family) steps.push(`set pref-src ${set.preferred_source}`);
+    if (set.blackhole) steps.push("set blackhole yes");
     if (rule.action) steps.push(rule.action);
     return steps;
 }
@@ -1097,7 +1099,7 @@ function bgpConnections(out: Output, ctx: Context): void {
         const addressFamily = familyOf(neighbor.address);
         const internal = settings.remote_as === bgp.asn;
         const originates = bgp.networks?.some((prefix) => familyOf(host(prefix)) === family);
-        const role = settings.local_role ? ROLES[settings.local_role] : internal ? "ibgp" : "ebgp";
+        const role = settings.role ? ROLES[settings.role] : internal ? "ibgp" : "ebgp";
 
         out.add(
             "/routing bgp connection",

package/src/adapters/registries/peeringdb.ts

@@ -56,8 +56,8 @@ function peersWithRouteServer(device: Device, iface: AnyInterface): boolean {
 
     return Object.values(bgp?.neighbors ?? {}).some((neighbor) => {
         const group = neighbor.group ? bgp?.groups?.[neighbor.group] : undefined;
-        const role = neighbor.local_role ?? group?.local_role;
-        return role === "rs-client" && subnets.some((subnet) => contains(subnet, neighbor.address));
+        const role = neighbor.role ?? group?.role;
+        return role === "rs" && subnets.some((subnet) => contains(subnet, neighbor.address));
     });
 }
 

package/src/presets/index.ts

@@ -223,6 +223,8 @@ export type CommunityScheme<Class extends string = string> = {
     do_not_announce?: number;
     /** Set by a customer: prepend toward an AS once, twice or three times, `asn:function:asn`. */
     prepend?: { once?: number; twice?: number; three_times?: number };
+    /** Set by a customer: drop traffic to the route in your network, before it reaches them, `asn:function:0`. The route is never announced further. */
+    blackhole?: number;
 };
 
 const PREPENDS = [
@@ -238,6 +240,7 @@ const article = (word: string) => (/^[aeiou]/i.test(word) ? `an ${word}` : `a ${
  *
  * - `tag(neighborClass, neighborAs, { site, keepActions })`: a rule for an import policy. It removes your communities a neighbor set, then adds where the route was learned. `site` is needed when the scheme has `learned_at`. With `keepActions`, for a customer, its action communities stay.
  * - `actions(neighborAs)`: rules for an export policy toward one neighbor. They act on a customer's action communities, then remove all of yours. Place them before the rules that accept.
+ * - `blackhole(prefixSet)`: a rule for a customer's import policy, before anything that rejects long prefixes. It takes a route the customer asked to blackhole, but only inside `prefixSet`, its own space, and drops traffic to it here.
  * - `catalogue`: every community, for `communities` in `defineNetwork`.
  */
 export function communityScheme<const Class extends string>(scheme: CommunityScheme<Class>) {
@@ -272,7 +275,27 @@ export function communityScheme<const Class extends string>(scheme: CommunitySch
         };
     };
 
+    const blackhole = <S extends string>(prefixSet: S): PolicyRule<never, S> => {
+        if (scheme.blackhole === undefined) throw new Error("communityScheme: blackhole needs a function number in the scheme");
+
+        return {
+            description: "Blackhole, asked by the customer",
+            match: { large_community: community(scheme.blackhole, 0), prefix_set: prefixSet },
+            set: { blackhole: true },
+            action: "accept",
+        };
+    };
+
     const actions = (neighborAs: number): PolicyRule<never, never>[] => [
+        ...(scheme.blackhole !== undefined
+            ? [
+                  {
+                      description: "Blackholed here, never announced",
+                      match: { large_community: community(scheme.blackhole, 0) },
+                      action: "reject" as const,
+                  },
+              ]
+            : []),
         ...(scheme.do_not_announce !== undefined
             ? [
                   {
@@ -332,7 +355,10 @@ export function communityScheme<const Class extends string>(scheme: CommunitySch
             const fn = scheme.prepend?.[name];
             return fn === undefined ? [] : [{ community: community(fn, "nnn"), description: `Prepend ${name.replace("_", " ")} to AS$0` }];
         }),
+        ...(scheme.blackhole !== undefined
+            ? [{ community: community(scheme.blackhole, 0), description: `Blackhole: dropped in AS${asn}, not announced further` }]
+            : []),
     ];
 
-    return { community, tag, actions, catalogue };
+    return { community, tag, actions, blackhole, catalogue };
 }

package/src/schema/policy.ts

@@ -64,6 +64,8 @@ export type Sets = {
     next_hop?: IP;
     /** Source address for traffic the device itself sends to the route. Applies to routes of the same family as the address. */
     preferred_source?: IP;
+    /** Drop traffic to the route on this device, instead of forwarding it. */
+    blackhole?: true;
 };
 
 /**

package/src/schema/routing.ts

@@ -18,7 +18,9 @@ export type StaticRoute<I extends string, F extends string> = {
     description?: string;
 };
 
-/** Our side of the relationship, as RFC 9234 defines it. */
+/**
+ * What a BGP neighbor is to us, with the roles RFC 9234 defines: `provider`, a transit we buy from; `customer`, one we sell transit to; `peer`, one we exchange our own routes with; `rs`, an exchange's route server; `rs-client`, a network using our route server.
+ */
 export type BgpRole = "provider" | "customer" | "peer" | "rs" | "rs-client";
 
 /** Settings a BGP neighbor can state itself or take from its group. */
@@ -33,8 +35,8 @@ export type NeighborSettings<P extends string> = {
     import?: P;
     /** Policy for routes announced. Nothing is announced when absent. */
     export?: P;
-    /** Our role toward this neighbor, which lets both sides reject a leak. */
-    local_role?: BgpRole;
+    /** What the neighbor is to us, such as `provider` for a transit. Both sides then reject a route leak, after RFC 9234. */
+    role?: BgpRole;
     /** The neighbor is more than one hop away. */
     multihop?: boolean;
     /** TCP MD5 password shared with the neighbor. */

package/templates/colocation/edge-01.ts

@@ -67,7 +67,7 @@ export default defineDevice({
                 "example-transit": {
                     address: "203.0.113.1",
                     remote_as: 64501,
-                    local_role: "customer",
+                    role: "provider",
                     import: "TRANSIT-IN",
                     export: "OUT",
                     max_prefixes: 1_200_000,
@@ -75,7 +75,7 @@ export default defineDevice({
                 "example-ix-rs-v4": {
                     address: "192.0.2.1",
                     remote_as: 64502,
-                    local_role: "rs-client",
+                    role: "rs",
                     import: "IX-IN",
                     export: "OUT",
                     max_prefixes: 100_000,
@@ -83,7 +83,7 @@ export default defineDevice({
                 "example-ix-rs-v6": {
                     address: "2001:db8:ffff::1",
                     remote_as: 64502,
-                    local_role: "rs-client",
+                    role: "rs",
                     import: "IX-IN",
                     export: "OUT",
                     max_prefixes: 50_000,

package/templates/edge-router/edge-01.ts

@@ -51,7 +51,7 @@ export default defineDevice({
                 "example-transit": {
                     address: "203.0.113.1",
                     remote_as: 64501,
-                    local_role: "customer",
+                    role: "provider",
                     import: "TRANSIT-IN",
                     export: "OUT",
                     max_prefixes: 1_200_000,
@@ -59,7 +59,7 @@ export default defineDevice({
                 "example-ix-rs-v4": {
                     address: "192.0.2.1",
                     remote_as: 64502,
-                    local_role: "rs-client",
+                    role: "rs",
                     import: "IX-IN",
                     export: "OUT",
                     max_prefixes: 100_000,
@@ -67,7 +67,7 @@ export default defineDevice({
                 "example-ix-rs-v6": {
                     address: "2001:db8:ffff::1",
                     remote_as: 64502,
-                    local_role: "rs-client",
+                    role: "rs",
                     import: "IX-IN",
                     export: "OUT",
                     max_prefixes: 50_000,