github.com/rajeev159/opa@v0.45.0/ast/builtins.go (about) 1 // Copyright 2016 The OPA Authors. All rights reserved. 2 // Use of this source code is governed by an Apache2 3 // license that can be found in the LICENSE file. 4 5 package ast 6 7 import ( 8 "strings" 9 10 "github.com/open-policy-agent/opa/types" 11 ) 12 13 // Builtins is the registry of built-in functions supported by OPA. 14 // Call RegisterBuiltin to add a new built-in. 15 var Builtins []*Builtin 16 17 // RegisterBuiltin adds a new built-in function to the registry. 18 func RegisterBuiltin(b *Builtin) { 19 Builtins = append(Builtins, b) 20 BuiltinMap[b.Name] = b 21 if len(b.Infix) > 0 { 22 BuiltinMap[b.Infix] = b 23 } 24 } 25 26 // DefaultBuiltins is the registry of built-in functions supported in OPA 27 // by default. When adding a new built-in function to OPA, update this 28 // list. 29 var DefaultBuiltins = [...]*Builtin{ 30 // Unification/equality ("=") 31 Equality, 32 33 // Assignment (":=") 34 Assign, 35 36 // Membership, infix "in": `x in xs` 37 Member, 38 MemberWithKey, 39 40 // Comparisons 41 GreaterThan, 42 GreaterThanEq, 43 LessThan, 44 LessThanEq, 45 NotEqual, 46 Equal, 47 48 // Arithmetic 49 Plus, 50 Minus, 51 Multiply, 52 Divide, 53 Ceil, 54 Floor, 55 Round, 56 Abs, 57 Rem, 58 59 // Bitwise Arithmetic 60 BitsOr, 61 BitsAnd, 62 BitsNegate, 63 BitsXOr, 64 BitsShiftLeft, 65 BitsShiftRight, 66 67 // Binary 68 And, 69 Or, 70 71 // Aggregates 72 Count, 73 Sum, 74 Product, 75 Max, 76 Min, 77 Any, 78 All, 79 80 // Arrays 81 ArrayConcat, 82 ArraySlice, 83 ArrayReverse, 84 85 // Conversions 86 ToNumber, 87 88 // Casts (DEPRECATED) 89 CastObject, 90 CastNull, 91 CastBoolean, 92 CastString, 93 CastSet, 94 CastArray, 95 96 // Regular Expressions 97 RegexIsValid, 98 RegexMatch, 99 RegexMatchDeprecated, 100 RegexSplit, 101 GlobsMatch, 102 RegexTemplateMatch, 103 RegexFind, 104 RegexFindAllStringSubmatch, 105 106 // Sets 107 SetDiff, 108 Intersection, 109 Union, 110 111 // Strings 112 Concat, 113 FormatInt, 114 IndexOf, 115 IndexOfN, 116 Substring, 117 Lower, 118 Upper, 119 Contains, 120 StartsWith, 121 EndsWith, 122 Split, 123 Replace, 124 ReplaceN, 125 Trim, 126 TrimLeft, 127 TrimPrefix, 128 TrimRight, 129 TrimSuffix, 130 TrimSpace, 131 Sprintf, 132 StringReverse, 133 134 // Numbers 135 NumbersRange, 136 RandIntn, 137 138 // Encoding 139 JSONMarshal, 140 JSONUnmarshal, 141 JSONIsValid, 142 Base64Encode, 143 Base64Decode, 144 Base64IsValid, 145 Base64UrlEncode, 146 Base64UrlEncodeNoPad, 147 Base64UrlDecode, 148 URLQueryDecode, 149 URLQueryEncode, 150 URLQueryEncodeObject, 151 URLQueryDecodeObject, 152 YAMLMarshal, 153 YAMLUnmarshal, 154 YAMLIsValid, 155 HexEncode, 156 HexDecode, 157 158 // Object Manipulation 159 ObjectUnion, 160 ObjectUnionN, 161 ObjectRemove, 162 ObjectFilter, 163 ObjectGet, 164 ObjectSubset, 165 166 // JSON Object Manipulation 167 JSONFilter, 168 JSONRemove, 169 JSONPatch, 170 171 // Tokens 172 JWTDecode, 173 JWTVerifyRS256, 174 JWTVerifyRS384, 175 JWTVerifyRS512, 176 JWTVerifyPS256, 177 JWTVerifyPS384, 178 JWTVerifyPS512, 179 JWTVerifyES256, 180 JWTVerifyES384, 181 JWTVerifyES512, 182 JWTVerifyHS256, 183 JWTVerifyHS384, 184 JWTVerifyHS512, 185 JWTDecodeVerify, 186 JWTEncodeSignRaw, 187 JWTEncodeSign, 188 189 // Time 190 NowNanos, 191 ParseNanos, 192 ParseRFC3339Nanos, 193 ParseDurationNanos, 194 Date, 195 Clock, 196 Weekday, 197 AddDate, 198 Diff, 199 200 // Crypto 201 CryptoX509ParseCertificates, 202 CryptoX509ParseAndVerifyCertificates, 203 CryptoMd5, 204 CryptoSha1, 205 CryptoSha256, 206 CryptoX509ParseCertificateRequest, 207 CryptoX509ParseRSAPrivateKey, 208 CryptoHmacMd5, 209 CryptoHmacSha1, 210 CryptoHmacSha256, 211 CryptoHmacSha512, 212 213 // Graphs 214 WalkBuiltin, 215 ReachableBuiltin, 216 ReachablePathsBuiltin, 217 218 // Sort 219 Sort, 220 221 // Types 222 IsNumber, 223 IsString, 224 IsBoolean, 225 IsArray, 226 IsSet, 227 IsObject, 228 IsNull, 229 TypeNameBuiltin, 230 231 // HTTP 232 HTTPSend, 233 234 // GraphQL 235 GraphQLParse, 236 GraphQLParseAndVerify, 237 GraphQLParseQuery, 238 GraphQLParseSchema, 239 GraphQLIsValid, 240 241 // Rego 242 RegoParseModule, 243 RegoMetadataChain, 244 RegoMetadataRule, 245 246 // OPA 247 OPARuntime, 248 249 // Tracing 250 Trace, 251 252 // Networking 253 NetCIDROverlap, 254 NetCIDRIntersects, 255 NetCIDRContains, 256 NetCIDRContainsMatches, 257 NetCIDRExpand, 258 NetCIDRMerge, 259 NetLookupIPAddr, 260 261 // Glob 262 GlobMatch, 263 GlobQuoteMeta, 264 265 // Units 266 UnitsParse, 267 UnitsParseBytes, 268 269 // UUIDs 270 UUIDRFC4122, 271 272 //SemVers 273 SemVerIsValid, 274 SemVerCompare, 275 276 // Printing 277 Print, 278 InternalPrint, 279 } 280 281 // BuiltinMap provides a convenient mapping of built-in names to 282 // built-in definitions. 283 var BuiltinMap map[string]*Builtin 284 285 // IgnoreDuringPartialEval is a set of built-in functions that should not be 286 // evaluated during partial evaluation. These functions are not partially 287 // evaluated because they are not pure. 288 var IgnoreDuringPartialEval = []*Builtin{ 289 NowNanos, 290 HTTPSend, 291 UUIDRFC4122, 292 RandIntn, 293 NetLookupIPAddr, 294 } 295 296 /** 297 * Unification 298 */ 299 300 // Equality represents the "=" operator. 301 var Equality = &Builtin{ 302 Name: "eq", 303 Infix: "=", 304 Decl: types.NewFunction( 305 types.Args(types.A, types.A), 306 types.B, 307 ), 308 } 309 310 /** 311 * Assignment 312 */ 313 314 // Assign represents the assignment (":=") operator. 315 var Assign = &Builtin{ 316 Name: "assign", 317 Infix: ":=", 318 Decl: types.NewFunction( 319 types.Args(types.A, types.A), 320 types.B, 321 ), 322 } 323 324 // Member represents the `in` (infix) operator. 325 var Member = &Builtin{ 326 Name: "internal.member_2", 327 Infix: "in", 328 Decl: types.NewFunction( 329 types.Args( 330 types.A, 331 types.A, 332 ), 333 types.B, 334 ), 335 } 336 337 // MemberWithKey represents the `in` (infix) operator when used 338 // with two terms on the lhs, i.e., `k, v in obj`. 339 var MemberWithKey = &Builtin{ 340 Name: "internal.member_3", 341 Infix: "in", 342 Decl: types.NewFunction( 343 types.Args( 344 types.A, 345 types.A, 346 types.A, 347 ), 348 types.B, 349 ), 350 } 351 352 /** 353 * Comparisons 354 */ 355 var comparison = category("comparison") 356 357 var GreaterThan = &Builtin{ 358 Name: "gt", 359 Infix: ">", 360 Categories: comparison, 361 Decl: types.NewFunction( 362 types.Args( 363 types.Named("x", types.A), 364 types.Named("y", types.A), 365 ), 366 types.Named("result", types.B).Description("true if `x` is greater than `y`; false otherwise"), 367 ), 368 } 369 370 var GreaterThanEq = &Builtin{ 371 Name: "gte", 372 Infix: ">=", 373 Categories: comparison, 374 Decl: types.NewFunction( 375 types.Args( 376 types.Named("x", types.A), 377 types.Named("y", types.A), 378 ), 379 types.Named("result", types.B).Description("true if `x` is greater or equal to `y`; false otherwise"), 380 ), 381 } 382 383 // LessThan represents the "<" comparison operator. 384 var LessThan = &Builtin{ 385 Name: "lt", 386 Infix: "<", 387 Categories: comparison, 388 Decl: types.NewFunction( 389 types.Args( 390 types.Named("x", types.A), 391 types.Named("y", types.A), 392 ), 393 types.Named("result", types.B).Description("true if `x` is less than `y`; false otherwise"), 394 ), 395 } 396 397 var LessThanEq = &Builtin{ 398 Name: "lte", 399 Infix: "<=", 400 Categories: comparison, 401 Decl: types.NewFunction( 402 types.Args( 403 types.Named("x", types.A), 404 types.Named("y", types.A), 405 ), 406 types.Named("result", types.B).Description("true if `x` is less than or equal to `y`; false otherwise"), 407 ), 408 } 409 410 var NotEqual = &Builtin{ 411 Name: "neq", 412 Infix: "!=", 413 Categories: comparison, 414 Decl: types.NewFunction( 415 types.Args( 416 types.Named("x", types.A), 417 types.Named("y", types.A), 418 ), 419 types.Named("result", types.B).Description("true if `x` is not equal to `y`; false otherwise"), 420 ), 421 } 422 423 // Equal represents the "==" comparison operator. 424 var Equal = &Builtin{ 425 Name: "equal", 426 Infix: "==", 427 Categories: comparison, 428 Decl: types.NewFunction( 429 types.Args( 430 types.Named("x", types.A), 431 types.Named("y", types.A), 432 ), 433 types.Named("result", types.B).Description("true if `x` is equal to `y`; false otherwise"), 434 ), 435 } 436 437 /** 438 * Arithmetic 439 */ 440 var number = category("numbers") 441 442 var Plus = &Builtin{ 443 Name: "plus", 444 Infix: "+", 445 Description: "Plus adds two numbers together.", 446 Decl: types.NewFunction( 447 types.Args( 448 types.Named("x", types.N), 449 types.Named("y", types.N), 450 ), 451 types.Named("z", types.N).Description("the sum of `x` and `y`"), 452 ), 453 Categories: number, 454 } 455 456 var Minus = &Builtin{ 457 Name: "minus", 458 Infix: "-", 459 Description: "Minus subtracts the second number from the first number or computes the difference between two sets.", 460 Decl: types.NewFunction( 461 types.Args( 462 types.Named("x", types.NewAny(types.N, types.NewSet(types.A))), 463 types.Named("y", types.NewAny(types.N, types.NewSet(types.A))), 464 ), 465 types.Named("z", types.NewAny(types.N, types.NewSet(types.A))).Description("the difference of `x` and `y`"), 466 ), 467 Categories: category("sets", "numbers"), 468 } 469 470 var Multiply = &Builtin{ 471 Name: "mul", 472 Infix: "*", 473 Description: "Multiplies two numbers.", 474 Decl: types.NewFunction( 475 types.Args( 476 types.Named("x", types.N), 477 types.Named("y", types.N), 478 ), 479 types.Named("z", types.N).Description("the product of `x` and `y`"), 480 ), 481 Categories: number, 482 } 483 484 var Divide = &Builtin{ 485 Name: "div", 486 Infix: "/", 487 Description: "Divides the first number by the second number.", 488 Decl: types.NewFunction( 489 types.Args( 490 types.Named("x", types.N).Description("the dividend"), 491 types.Named("y", types.N).Description("the divisor"), 492 ), 493 types.Named("z", types.N).Description("the result of `x` divided by `y`"), 494 ), 495 Categories: number, 496 } 497 498 var Round = &Builtin{ 499 Name: "round", 500 Description: "Rounds the number to the nearest integer.", 501 Decl: types.NewFunction( 502 types.Args( 503 types.Named("x", types.N).Description("the number to round"), 504 ), 505 types.Named("y", types.N).Description("the result of rounding `x`"), 506 ), 507 Categories: number, 508 } 509 510 var Ceil = &Builtin{ 511 Name: "ceil", 512 Description: "Rounds the number _up_ to the nearest integer.", 513 Decl: types.NewFunction( 514 types.Args( 515 types.Named("x", types.N).Description("the number to round"), 516 ), 517 types.Named("y", types.N).Description("the result of rounding `x` _up_"), 518 ), 519 Categories: number, 520 } 521 522 var Floor = &Builtin{ 523 Name: "floor", 524 Description: "Rounds the number _down_ to the nearest integer.", 525 Decl: types.NewFunction( 526 types.Args( 527 types.Named("x", types.N).Description("the number to round"), 528 ), 529 types.Named("y", types.N).Description("the result of rounding `x` _down_"), 530 ), 531 Categories: number, 532 } 533 534 var Abs = &Builtin{ 535 Name: "abs", 536 Description: "Returns the number without its sign.", 537 Decl: types.NewFunction( 538 types.Args( 539 types.Named("x", types.N), 540 ), 541 types.Named("y", types.N).Description("the absolute value of `x`"), 542 ), 543 Categories: number, 544 } 545 546 var Rem = &Builtin{ 547 Name: "rem", 548 Infix: "%", 549 Description: "Returns the remainder for of `x` divided by `y`, for `y != 0`.", 550 Decl: types.NewFunction( 551 types.Args( 552 types.Named("x", types.N), 553 types.Named("y", types.N), 554 ), 555 types.Named("z", types.N).Description("the remainder"), 556 ), 557 Categories: number, 558 } 559 560 /** 561 * Bitwise 562 */ 563 564 var BitsOr = &Builtin{ 565 Name: "bits.or", 566 Description: "Returns the bitwise \"OR\" of two integers.", 567 Decl: types.NewFunction( 568 types.Args( 569 types.Named("x", types.N), 570 types.Named("y", types.N), 571 ), 572 types.Named("z", types.N), 573 ), 574 } 575 576 var BitsAnd = &Builtin{ 577 Name: "bits.and", 578 Description: "Returns the bitwise \"AND\" of two integers.", 579 Decl: types.NewFunction( 580 types.Args( 581 types.Named("x", types.N), 582 types.Named("y", types.N), 583 ), 584 types.Named("z", types.N), 585 ), 586 } 587 588 var BitsNegate = &Builtin{ 589 Name: "bits.negate", 590 Description: "Returns the bitwise negation (flip) of an integer.", 591 Decl: types.NewFunction( 592 types.Args( 593 types.Named("x", types.N), 594 ), 595 types.Named("z", types.N), 596 ), 597 } 598 599 var BitsXOr = &Builtin{ 600 Name: "bits.xor", 601 Description: "Returns the bitwise \"XOR\" (exclusive-or) of two integers.", 602 Decl: types.NewFunction( 603 types.Args( 604 types.Named("x", types.N), 605 types.Named("y", types.N), 606 ), 607 types.Named("z", types.N), 608 ), 609 } 610 611 var BitsShiftLeft = &Builtin{ 612 Name: "bits.lsh", 613 Description: "Returns a new integer with its bits shifted `s` bits to the left.", 614 Decl: types.NewFunction( 615 types.Args( 616 types.Named("x", types.N), 617 types.Named("s", types.N), 618 ), 619 types.Named("z", types.N), 620 ), 621 } 622 623 var BitsShiftRight = &Builtin{ 624 Name: "bits.rsh", 625 Description: "Returns a new integer with its bits shifted `s` bits to the right.", 626 Decl: types.NewFunction( 627 types.Args( 628 types.Named("x", types.N), 629 types.Named("s", types.N), 630 ), 631 types.Named("z", types.N), 632 ), 633 } 634 635 /** 636 * Sets 637 */ 638 639 var sets = category("sets") 640 641 var And = &Builtin{ 642 Name: "and", 643 Infix: "&", 644 Description: "Returns the intersection of two sets.", 645 Decl: types.NewFunction( 646 types.Args( 647 types.Named("x", types.NewSet(types.A)), 648 types.Named("y", types.NewSet(types.A)), 649 ), 650 types.Named("z", types.NewSet(types.A)).Description("the intersection of `x` and `y`"), 651 ), 652 Categories: sets, 653 } 654 655 // Or performs a union operation on sets. 656 var Or = &Builtin{ 657 Name: "or", 658 Infix: "|", 659 Description: "Returns the union of two sets.", 660 Decl: types.NewFunction( 661 types.Args( 662 types.Named("x", types.NewSet(types.A)), 663 types.Named("y", types.NewSet(types.A)), 664 ), 665 types.Named("z", types.NewSet(types.A)).Description("the union of `x` and `y`"), 666 ), 667 Categories: sets, 668 } 669 670 var Intersection = &Builtin{ 671 Name: "intersection", 672 Description: "Returns the intersection of the given input sets.", 673 Decl: types.NewFunction( 674 types.Args( 675 types.Named("xs", types.NewSet(types.NewSet(types.A))).Description("set of sets to intersect"), 676 ), 677 types.Named("y", types.NewSet(types.A)).Description("the intersection of all `xs` sets"), 678 ), 679 Categories: sets, 680 } 681 682 var Union = &Builtin{ 683 Name: "union", 684 Description: "Returns the union of the given input sets.", 685 Decl: types.NewFunction( 686 types.Args( 687 types.Named("xs", types.NewSet(types.NewSet(types.A))).Description("set of sets to merge"), 688 ), 689 types.Named("y", types.NewSet(types.A)).Description("the union of all `xs` sets"), 690 ), 691 Categories: sets, 692 } 693 694 /** 695 * Aggregates 696 */ 697 698 var aggregates = category("aggregates") 699 700 var Count = &Builtin{ 701 Name: "count", 702 Description: " Count takes a collection or string and returns the number of elements (or characters) in it.", 703 Decl: types.NewFunction( 704 types.Args( 705 types.Named("collection", types.NewAny( 706 types.NewSet(types.A), 707 types.NewArray(nil, types.A), 708 types.NewObject(nil, types.NewDynamicProperty(types.A, types.A)), 709 types.S, 710 )).Description("the set/array/object/string to be counted"), 711 ), 712 types.Named("n", types.N).Description("the count of elements, key/val pairs, or characters, respectively."), 713 ), 714 Categories: aggregates, 715 } 716 717 var Sum = &Builtin{ 718 Name: "sum", 719 Description: "Sums elements of an array or set of numbers.", 720 Decl: types.NewFunction( 721 types.Args( 722 types.Named("collection", types.NewAny( 723 types.NewSet(types.N), 724 types.NewArray(nil, types.N), 725 )), 726 ), 727 types.Named("n", types.N).Description("the sum of all elements"), 728 ), 729 Categories: aggregates, 730 } 731 732 var Product = &Builtin{ 733 Name: "product", 734 Description: "Muliplies elements of an array or set of numbers", 735 Decl: types.NewFunction( 736 types.Args( 737 types.Named("collection", types.NewAny( 738 types.NewSet(types.N), 739 types.NewArray(nil, types.N), 740 )), 741 ), 742 types.Named("n", types.N).Description("the product of all elements"), 743 ), 744 Categories: aggregates, 745 } 746 747 var Max = &Builtin{ 748 Name: "max", 749 Description: "Returns the maximum value in a collection.", 750 Decl: types.NewFunction( 751 types.Args( 752 types.Named("collection", types.NewAny( 753 types.NewSet(types.A), 754 types.NewArray(nil, types.A), 755 )), 756 ), 757 types.Named("n", types.A).Description("the maximum of all elements"), 758 ), 759 Categories: aggregates, 760 } 761 762 var Min = &Builtin{ 763 Name: "min", 764 Description: "Returns the minimum value in a collection.", 765 Decl: types.NewFunction( 766 types.Args( 767 types.Named("collection", types.NewAny( 768 types.NewSet(types.A), 769 types.NewArray(nil, types.A), 770 )), 771 ), 772 types.Named("n", types.A).Description("the minimum of all elements"), 773 ), 774 Categories: aggregates, 775 } 776 777 /** 778 * Sorting 779 */ 780 781 var Sort = &Builtin{ 782 Name: "sort", 783 Description: "Returns a sorted array.", 784 Decl: types.NewFunction( 785 types.Args( 786 types.Named("collection", types.NewAny( 787 types.NewArray(nil, types.A), 788 types.NewSet(types.A), 789 )).Description("the array or set to be sorted"), 790 ), 791 types.Named("n", types.NewArray(nil, types.A)).Description("the sorted array"), 792 ), 793 Categories: aggregates, 794 } 795 796 /** 797 * Arrays 798 */ 799 800 var ArrayConcat = &Builtin{ 801 Name: "array.concat", 802 Description: "Concatenates two arrays.", 803 Decl: types.NewFunction( 804 types.Args( 805 types.Named("x", types.NewArray(nil, types.A)), 806 types.Named("y", types.NewArray(nil, types.A)), 807 ), 808 types.Named("z", types.NewArray(nil, types.A)).Description("the concatenation of `x` and `y`"), 809 ), 810 } 811 812 var ArraySlice = &Builtin{ 813 Name: "array.slice", 814 Description: "Returns a slice of a given array. If `start` is greater or equal than `stop`, `slice` is `[]`.", 815 Decl: types.NewFunction( 816 types.Args( 817 types.Named("arr", types.NewArray(nil, types.A)).Description("the array to be sliced"), 818 types.Named("start", types.NewNumber()).Description("the start index of the returned slice; if less than zero, it's clamped to 0"), 819 types.Named("stop", types.NewNumber()).Description("the stop index of the returned slice; if larger than `count(arr)`, it's clamped to `count(arr)`"), 820 ), 821 types.Named("slice", types.NewArray(nil, types.A)).Description("the subslice of `array`, from `start` to `end`, including `arr[start]`, but excluding `arr[end]`"), 822 ), 823 } // NOTE(sr): this function really needs examples 824 825 var ArrayReverse = &Builtin{ 826 Name: "array.reverse", 827 Description: "Returns the reverse of a given array.", 828 Decl: types.NewFunction( 829 types.Args( 830 types.Named("arr", types.NewArray(nil, types.A)).Description("the array to be reversed"), 831 ), 832 types.Named("rev", types.NewArray(nil, types.A)).Description("an array containing the elements of `arr` in reverse order"), 833 ), 834 } 835 836 /** 837 * Conversions 838 */ 839 var conversions = category("conversions") 840 841 var ToNumber = &Builtin{ 842 Name: "to_number", 843 Description: "Converts a string, bool, or number value to a number: Strings are converted to numbers using `strconv.Atoi`, Boolean `false` is converted to 0 and `true` is converted to 1.", 844 Decl: types.NewFunction( 845 types.Args( 846 types.Named("x", types.NewAny( 847 types.N, 848 types.S, 849 types.B, 850 types.NewNull(), 851 )), 852 ), 853 types.Named("num", types.N), 854 ), 855 Categories: conversions, 856 } 857 858 /** 859 * Regular Expressions 860 */ 861 862 var RegexMatch = &Builtin{ 863 Name: "regex.match", 864 Description: "Matches a string against a regular expression.", 865 Decl: types.NewFunction( 866 types.Args( 867 types.Named("pattern", types.S).Description("regular expression"), 868 types.Named("value", types.S).Description("value to match against `pattern`"), 869 ), 870 types.Named("result", types.B), 871 ), 872 } 873 874 var RegexIsValid = &Builtin{ 875 Name: "regex.is_valid", 876 Description: "Checks if a string is a valid regular expression: the detailed syntax for patterns is defined by https://github.com/google/re2/wiki/Syntax.", 877 Decl: types.NewFunction( 878 types.Args( 879 types.Named("pattern", types.S).Description("regular expression"), 880 ), 881 types.Named("result", types.B), 882 ), 883 } 884 885 var RegexFindAllStringSubmatch = &Builtin{ 886 Name: "regex.find_all_string_submatch_n", 887 Description: "Returns all successive matches of the expression.", 888 Decl: types.NewFunction( 889 types.Args( 890 types.Named("pattern", types.S).Description("regular expression"), 891 types.Named("value", types.S).Description("string to match"), 892 types.Named("number", types.N).Description("number of matches to return; `-1` means all matches"), 893 ), 894 types.Named("output", types.NewArray(nil, types.NewArray(nil, types.S))), 895 ), 896 } 897 898 var RegexTemplateMatch = &Builtin{ 899 Name: "regex.template_match", 900 Description: "Matches a string against a pattern, where there pattern may be glob-like", 901 Decl: types.NewFunction( 902 types.Args( 903 types.Named("template", types.S).Description("template expression containing `0..n` regular expressions"), 904 types.Named("value", types.S).Description("string to match"), 905 types.Named("delimiter_start", types.S).Description("start delimiter of the regular expression in `template`"), 906 types.Named("delimiter_end", types.S).Description("end delimiter of the regular expression in `template`"), 907 ), 908 types.Named("result", types.B), 909 ), 910 } // TODO(sr): example:`regex.template_match("urn:foo:{.*}", "urn:foo:bar:baz", "{", "}")`` returns ``true``. 911 912 var RegexSplit = &Builtin{ 913 Name: "regex.split", 914 Description: "Splits the input string by the occurrences of the given pattern.", 915 Decl: types.NewFunction( 916 types.Args( 917 types.Named("pattern", types.S).Description("regular expression"), 918 types.Named("value", types.S).Description("string to match"), 919 ), 920 types.Named("output", types.NewArray(nil, types.S)).Description("the parts obtained by splitting `value`"), 921 ), 922 } 923 924 // RegexFind takes two strings and a number, the pattern, the value and number of match values to 925 // return, -1 means all match values. 926 var RegexFind = &Builtin{ 927 Name: "regex.find_n", 928 Description: "Returns the specified number of matches when matching the input against the pattern.", 929 Decl: types.NewFunction( 930 types.Args( 931 types.Named("pattern", types.S).Description("regular expression"), 932 types.Named("value", types.S).Description("string to match"), 933 types.Named("number", types.N).Description("number of matches to return, if `-1`, returns all matches"), 934 ), 935 types.Named("output", types.NewArray(nil, types.S)).Description("collected matches"), 936 ), 937 } 938 939 // GlobsMatch takes two strings regexp-style strings and evaluates to true if their 940 // intersection matches a non-empty set of non-empty strings. 941 // Examples: 942 // - "a.a." and ".b.b" -> true. 943 // - "[a-z]*" and [0-9]+" -> not true. 944 var GlobsMatch = &Builtin{ 945 Name: "regex.globs_match", 946 Description: `Checks if the intersection of two glob-style regular expressions matches a non-empty set of non-empty strings. 947 The set of regex symbols is limited for this builtin: only ` + "`.`, `*`, `+`, `[`, `-`, `]` and `\\` are treated as special symbols.", 948 Decl: types.NewFunction( 949 types.Args( 950 types.Named("glob1", types.S), 951 types.Named("glob2", types.S), 952 ), 953 types.Named("result", types.B), 954 ), 955 } 956 957 /** 958 * Strings 959 */ 960 var stringsCat = category("strings") 961 962 var Concat = &Builtin{ 963 Name: "concat", 964 Description: "Joins a set or array of strings with a delimiter.", 965 Decl: types.NewFunction( 966 types.Args( 967 types.Named("delimiter", types.S), 968 types.Named("collection", types.NewAny( 969 types.NewSet(types.S), 970 types.NewArray(nil, types.S), 971 )).Description("strings to join"), 972 ), 973 types.Named("output", types.S), 974 ), 975 Categories: stringsCat, 976 } 977 978 var FormatInt = &Builtin{ 979 Name: "format_int", 980 Description: "Returns the string representation of the number in the given base after converting it to an integer value.", 981 Decl: types.NewFunction( 982 types.Args( 983 types.Named("number", types.N).Description("number to format"), 984 types.Named("base", types.N).Description("base of number representation to use"), 985 ), 986 types.Named("output", types.S).Description("formatted number"), 987 ), 988 Categories: stringsCat, 989 } 990 991 var IndexOf = &Builtin{ 992 Name: "indexof", 993 Description: "Returns the index of a substring contained inside a string.", 994 Decl: types.NewFunction( 995 types.Args( 996 types.Named("haystack", types.S).Description("string to search in"), 997 types.Named("needle", types.S).Description("substring to look for"), 998 ), 999 types.Named("output", types.N).Description("index of first occurrence, `-1` if not found"), 1000 ), 1001 Categories: stringsCat, 1002 } 1003 1004 var IndexOfN = &Builtin{ 1005 Name: "indexof_n", 1006 Description: "Returns a list of all the indexes of a substring contained inside a string.", 1007 Decl: types.NewFunction( 1008 types.Args( 1009 types.Named("haystack", types.S).Description("string to search in"), 1010 types.Named("needle", types.S).Description("substring to look for"), 1011 ), 1012 types.Named("output", types.NewArray(nil, types.N)).Description("all indices at which `needle` occurs in `haystack`, may be empty"), 1013 ), 1014 Categories: stringsCat, 1015 } 1016 1017 var Substring = &Builtin{ 1018 Name: "substring", 1019 Description: "Returns the portion of a string for a given `offset` and a `length`. If `length < 0`, `output` is the remainder of the string.", 1020 Decl: types.NewFunction( 1021 types.Args( 1022 types.Named("value", types.S), 1023 types.Named("offset", types.N).Description("offset, must be positive"), 1024 types.Named("length", types.N).Description("length of the substring starting from `offset`"), 1025 ), 1026 types.Named("output", types.S).Description("substring of `value` from `offset`, of length `length`"), 1027 ), 1028 Categories: stringsCat, 1029 } 1030 1031 var Contains = &Builtin{ 1032 Name: "contains", 1033 Description: "Returns `true` if the search string is included in the base string", 1034 Decl: types.NewFunction( 1035 types.Args( 1036 types.Named("haystack", types.S).Description("string to search in"), 1037 types.Named("needle", types.S).Description("substring to look for"), 1038 ), 1039 types.Named("result", types.B).Description("result of the containment check"), 1040 ), 1041 Categories: stringsCat, 1042 } 1043 1044 var StartsWith = &Builtin{ 1045 Name: "startswith", 1046 Description: "Returns true if the search string begins with the base string.", 1047 Decl: types.NewFunction( 1048 types.Args( 1049 types.Named("search", types.S).Description("search string"), 1050 types.Named("base", types.S).Description("base string"), 1051 ), 1052 types.Named("result", types.B).Description("result of the prefix check"), 1053 ), 1054 Categories: stringsCat, 1055 } 1056 1057 var EndsWith = &Builtin{ 1058 Name: "endswith", 1059 Description: "Returns true if the search string ends with the base string.", 1060 Decl: types.NewFunction( 1061 types.Args( 1062 types.Named("search", types.S).Description("search string"), 1063 types.Named("base", types.S).Description("base string"), 1064 ), 1065 types.Named("result", types.B).Description("result of the suffix check"), 1066 ), 1067 Categories: stringsCat, 1068 } 1069 1070 var Lower = &Builtin{ 1071 Name: "lower", 1072 Description: "Returns the input string but with all characters in lower-case.", 1073 Decl: types.NewFunction( 1074 types.Args( 1075 types.Named("x", types.S).Description("string that is converted to lower-case"), 1076 ), 1077 types.Named("y", types.S).Description("lower-case of x"), 1078 ), 1079 Categories: stringsCat, 1080 } 1081 1082 var Upper = &Builtin{ 1083 Name: "upper", 1084 Description: "Returns the input string but with all characters in upper-case.", 1085 Decl: types.NewFunction( 1086 types.Args( 1087 types.Named("x", types.S).Description("string that is converted to upper-case"), 1088 ), 1089 types.Named("y", types.S).Description("upper-case of x"), 1090 ), 1091 Categories: stringsCat, 1092 } 1093 1094 var Split = &Builtin{ 1095 Name: "split", 1096 Description: "Split returns an array containing elements of the input string split on a delimiter.", 1097 Decl: types.NewFunction( 1098 types.Args( 1099 types.Named("x", types.S).Description("string that is split"), 1100 types.Named("delimiter", types.S).Description("delimiter used for splitting"), 1101 ), 1102 types.Named("ys", types.NewArray(nil, types.S)).Description("splitted parts"), 1103 ), 1104 Categories: stringsCat, 1105 } 1106 1107 var Replace = &Builtin{ 1108 Name: "replace", 1109 Description: "Replace replaces all instances of a sub-string.", 1110 Decl: types.NewFunction( 1111 types.Args( 1112 types.Named("x", types.S).Description("string being processed"), 1113 types.Named("old", types.S).Description("substring to replace"), 1114 types.Named("new", types.S).Description("string to replace `old` with"), 1115 ), 1116 types.Named("y", types.S).Description("string with replaced substrings"), 1117 ), 1118 Categories: stringsCat, 1119 } 1120 1121 var ReplaceN = &Builtin{ 1122 Name: "strings.replace_n", 1123 Description: `Replaces a string from a list of old, new string pairs. 1124 Replacements are performed in the order they appear in the target string, without overlapping matches. 1125 The old string comparisons are done in argument order.`, 1126 Decl: types.NewFunction( 1127 types.Args( 1128 types.Named("patterns", types.NewObject( 1129 nil, 1130 types.NewDynamicProperty( 1131 types.S, 1132 types.S)), 1133 ).Description("replacement pairs"), 1134 types.Named("value", types.S).Description("string to replace substring matches in"), 1135 ), 1136 types.Named("output", types.S), 1137 ), 1138 } 1139 1140 var Trim = &Builtin{ 1141 Name: "trim", 1142 Description: "Returns `value` with all leading or trailing instances of the `cutset` characters removed.", 1143 Decl: types.NewFunction( 1144 types.Args( 1145 types.Named("value", types.S).Description("string to trim"), 1146 types.Named("cutset", types.S).Description("string of characters that are cut off"), 1147 ), 1148 types.Named("output", types.S).Description("string trimmed of `cutset` characters"), 1149 ), 1150 Categories: stringsCat, 1151 } 1152 1153 var TrimLeft = &Builtin{ 1154 Name: "trim_left", 1155 Description: "Returns `value` with all leading instances of the `cutset` chartacters removed.", 1156 Decl: types.NewFunction( 1157 types.Args( 1158 types.Named("value", types.S).Description("string to trim"), 1159 types.Named("cutset", types.S).Description("string of characters that are cut off on the left"), 1160 ), 1161 types.Named("output", types.S).Description("string left-trimmed of `cutset` characters"), 1162 ), 1163 Categories: stringsCat, 1164 } 1165 1166 var TrimPrefix = &Builtin{ 1167 Name: "trim_prefix", 1168 Description: "Returns `value` without the prefix. If `value` doesn't start with `prefix`, it is returned unchanged.", 1169 Decl: types.NewFunction( 1170 types.Args( 1171 types.Named("value", types.S).Description("string to trim"), 1172 types.Named("prefix", types.S).Description("prefix to cut off"), 1173 ), 1174 types.Named("output", types.S).Description("string with `prefix` cut off"), 1175 ), 1176 Categories: stringsCat, 1177 } 1178 1179 var TrimRight = &Builtin{ 1180 Name: "trim_right", 1181 Description: "Returns `value` with all trailing instances of the `cutset` chartacters removed.", 1182 Decl: types.NewFunction( 1183 types.Args( 1184 types.Named("value", types.S).Description("string to trim"), 1185 types.Named("cutset", types.S).Description("string of characters that are cut off on the right"), 1186 ), 1187 types.Named("output", types.S).Description("string right-trimmed of `cutset` characters"), 1188 ), 1189 Categories: stringsCat, 1190 } 1191 1192 var TrimSuffix = &Builtin{ 1193 Name: "trim_suffix", 1194 Description: "Returns `value` without the suffix. If `value` doesn't end with `suffix`, it is returned unchanged.", 1195 Decl: types.NewFunction( 1196 types.Args( 1197 types.Named("value", types.S).Description("string to trim"), 1198 types.Named("suffix", types.S).Description("suffix to cut off"), 1199 ), 1200 types.Named("output", types.S).Description("string with `suffix` cut off"), 1201 ), 1202 Categories: stringsCat, 1203 } 1204 1205 var TrimSpace = &Builtin{ 1206 Name: "trim_space", 1207 Description: "Return the given string with all leading and trailing white space removed.", 1208 Decl: types.NewFunction( 1209 types.Args( 1210 types.Named("value", types.S).Description("string to trim"), 1211 ), 1212 types.Named("output", types.S).Description("string leading and trailing white space cut off"), 1213 ), 1214 Categories: stringsCat, 1215 } 1216 1217 var Sprintf = &Builtin{ 1218 Name: "sprintf", 1219 Description: "Returns the given string, formatted.", 1220 Decl: types.NewFunction( 1221 types.Args( 1222 types.Named("format", types.S).Description("string with formatting verbs"), 1223 types.Named("values", types.NewArray(nil, types.A)).Description("arguments to format into formatting verbs"), 1224 ), 1225 types.Named("output", types.S).Description("`format` formatted by the values in `values`"), 1226 ), 1227 Categories: stringsCat, 1228 } 1229 1230 var StringReverse = &Builtin{ 1231 Name: "strings.reverse", 1232 Description: "Reverses a given string.", 1233 Decl: types.NewFunction( 1234 types.Args( 1235 types.Named("x", types.S), 1236 ), 1237 types.Named("y", types.S), 1238 ), 1239 Categories: stringsCat, 1240 } 1241 1242 /** 1243 * Numbers 1244 */ 1245 1246 // RandIntn returns a random number 0 - n 1247 var RandIntn = &Builtin{ 1248 Name: "rand.intn", 1249 Description: "Returns a random integer between `0` and `n` (`n` exlusive). If `n` is `0`, then `y` is always `0`. For any given argument pair (`str`, `n`), the output will be consistent throughout a query evaluation.", 1250 Decl: types.NewFunction( 1251 types.Args( 1252 types.Named("str", types.S), 1253 types.Named("n", types.N), 1254 ), 1255 types.Named("y", types.N).Description("random integer in the range `[0, abs(n))`"), 1256 ), 1257 Categories: number, 1258 } 1259 1260 var NumbersRange = &Builtin{ 1261 Name: "numbers.range", 1262 Description: "Returns an array of numbers in the given (inclusive) range. If `a==b`, then `range == [a]`; if `a > b`, then `range` is in descending order.", 1263 Decl: types.NewFunction( 1264 types.Args( 1265 types.Named("a", types.N), 1266 types.Named("b", types.N), 1267 ), 1268 types.Named("range", types.NewArray(nil, types.N)).Description("the range between `a` and `b`"), 1269 ), 1270 } 1271 1272 /** 1273 * Units 1274 */ 1275 1276 // UnitsParse 1277 var UnitsParse = &Builtin{ 1278 Name: "units.parse", 1279 Description: `Converts strings like "10G", "5K", "4M", "1500m" and the like into a number. 1280 This number can be a non-integer, such as 1.5, 0.22, etc. Supports standard metric decimal and 1281 binary SI units (e.g., K, Ki, M, Mi, G, Gi etc.) m, K, M, G, T, P, and E are treated as decimal 1282 units and Ki, Mi, Gi, Ti, Pi, and Ei are treated as binary units. 1283 1284 Note that 'm' and 'M' are case-sensitive, to allow distinguishing between "milli" and "mega" units respectively. Other units are case-insensitive.`, 1285 Decl: types.NewFunction( 1286 types.Args( 1287 types.Named("x", types.S).Description("the unit to parse"), 1288 ), 1289 types.Named("y", types.N).Description("the parsed number"), 1290 ), 1291 } 1292 1293 var UnitsParseBytes = &Builtin{ 1294 Name: "units.parse_bytes", 1295 Description: `Converts strings like "10GB", "5K", "4mb" into an integer number of bytes. 1296 Supports standard byte units (e.g., KB, KiB, etc.) KB, MB, GB, and TB are treated as decimal 1297 units and KiB, MiB, GiB, and TiB are treated as binary units. The bytes symbol (b/B) in the 1298 unit is optional and omitting it wil give the same result (e.g. Mi and MiB).`, 1299 Decl: types.NewFunction( 1300 types.Args( 1301 types.Named("x", types.S).Description("the byte unit to parse"), 1302 ), 1303 types.Named("y", types.N).Description("the parsed number"), 1304 ), 1305 } 1306 1307 // 1308 /** 1309 * Type 1310 */ 1311 1312 // UUIDRFC4122 returns a version 4 UUID string. 1313 var UUIDRFC4122 = &Builtin{ 1314 Name: "uuid.rfc4122", 1315 Description: "Returns a new UUIDv4.", 1316 Decl: types.NewFunction( 1317 types.Args( 1318 types.Named("k", types.S), 1319 ), 1320 types.Named("output", types.S).Description("a version 4 UUID; for any given `k`, the output will be consistent throughout a query evaluation"), 1321 ), 1322 } 1323 1324 /** 1325 * JSON 1326 */ 1327 1328 var objectCat = category("object") 1329 1330 var JSONFilter = &Builtin{ 1331 Name: "json.filter", 1332 Description: "Filters the object. " + 1333 "For example: `json.filter({\"a\": {\"b\": \"x\", \"c\": \"y\"}}, [\"a/b\"])` will result in `{\"a\": {\"b\": \"x\"}}`). " + 1334 "Paths are not filtered in-order and are deduplicated before being evaluated.", 1335 Decl: types.NewFunction( 1336 types.Args( 1337 types.Named("object", types.NewObject( 1338 nil, 1339 types.NewDynamicProperty(types.A, types.A), 1340 )), 1341 types.Named("paths", types.NewAny( 1342 types.NewArray( 1343 nil, 1344 types.NewAny( 1345 types.S, 1346 types.NewArray( 1347 nil, 1348 types.A, 1349 ), 1350 ), 1351 ), 1352 types.NewSet( 1353 types.NewAny( 1354 types.S, 1355 types.NewArray( 1356 nil, 1357 types.A, 1358 ), 1359 ), 1360 ), 1361 )).Description("JSON string paths"), 1362 ), 1363 types.Named("filtered", types.A).Description("remaining data from `object` with only keys specified in `paths`"), 1364 ), 1365 Categories: objectCat, 1366 } 1367 1368 var JSONRemove = &Builtin{ 1369 Name: "json.remove", 1370 Description: "Removes paths from an object. " + 1371 "For example: `json.remove({\"a\": {\"b\": \"x\", \"c\": \"y\"}}, [\"a/b\"])` will result in `{\"a\": {\"c\": \"y\"}}`. " + 1372 "Paths are not removed in-order and are deduplicated before being evaluated.", 1373 Decl: types.NewFunction( 1374 types.Args( 1375 types.Named("object", types.NewObject( 1376 nil, 1377 types.NewDynamicProperty(types.A, types.A), 1378 )), 1379 types.Named("paths", types.NewAny( 1380 types.NewArray( 1381 nil, 1382 types.NewAny( 1383 types.S, 1384 types.NewArray( 1385 nil, 1386 types.A, 1387 ), 1388 ), 1389 ), 1390 types.NewSet( 1391 types.NewAny( 1392 types.S, 1393 types.NewArray( 1394 nil, 1395 types.A, 1396 ), 1397 ), 1398 ), 1399 )).Description("JSON string paths"), 1400 ), 1401 types.Named("output", types.A).Description("result of removing all keys specified in `paths`"), 1402 ), 1403 Categories: objectCat, 1404 } 1405 1406 var JSONPatch = &Builtin{ 1407 Name: "json.patch", 1408 Description: "Patches an object according to RFC6902. " + 1409 "For example: `json.patch({\"a\": {\"foo\": 1}}, [{\"op\": \"add\", \"path\": \"/a/bar\", \"value\": 2}])` results in `{\"a\": {\"foo\": 1, \"bar\": 2}`. The patches are applied atomically: if any of them fails, the result will be undefined.", 1410 Decl: types.NewFunction( 1411 types.Args( 1412 types.Named("object", types.A), // TODO(sr): types.A? 1413 types.Named("patches", types.NewArray( 1414 nil, 1415 types.NewObject( 1416 []*types.StaticProperty{ 1417 {Key: "op", Value: types.S}, 1418 {Key: "path", Value: types.A}, 1419 }, 1420 types.NewDynamicProperty(types.A, types.A), 1421 ), 1422 )), 1423 ), 1424 types.Named("output", types.A).Description("result obtained after consecutively applying all patch operations in `patches`"), 1425 ), 1426 Categories: objectCat, 1427 } 1428 1429 var ObjectSubset = &Builtin{ 1430 Name: "object.subset", 1431 Description: "Determines if an object `sub` is a subset of another object `super`." + 1432 "Object `sub` is a subset of object `super` if and only if every key in `sub` is also in `super`, " + 1433 "**and** for all keys which `sub` and `super` share, they have the same value. " + 1434 "This function works with objects, sets, and arrays. " + 1435 "If both arguments are objects, then the operation is recursive, e.g. " + 1436 "`{\"c\": {\"x\": {10, 15, 20}}` is a subset of `{\"a\": \"b\", \"c\": {\"x\": {10, 15, 20, 25}, \"y\": \"z\"}`. " + 1437 "If both arguments are sets, then this function checks if every element of `sub` is a member of `super`, " + 1438 "but does not attempt to recurse. If both arguments are arrays, " + 1439 "then this function checks if `sub` appears contiguously in order within `super`, " + 1440 "and also does not attempt to recurse.", 1441 Decl: types.NewFunction( 1442 types.Args( 1443 types.Named("super", types.NewAny(types.NewObject( 1444 nil, 1445 types.NewDynamicProperty(types.A, types.A), 1446 ), 1447 types.NewSet(types.A), 1448 types.NewArray(nil, types.A), 1449 )).Description("object to test if sub is a subset of"), 1450 types.Named("sub", types.NewAny(types.NewObject( 1451 nil, 1452 types.NewDynamicProperty(types.A, types.A), 1453 ), 1454 types.NewSet(types.A), 1455 types.NewArray(nil, types.A), 1456 )).Description("object to test if super is a superset of"), 1457 ), 1458 types.Named("result", types.A).Description("`true` if `sub` is a subset of `super`"), 1459 ), 1460 } 1461 1462 var ObjectUnion = &Builtin{ 1463 Name: "object.union", 1464 Description: "Creates a new object of the asymmetric union of two objects. " + 1465 "For example: `object.union({\"a\": 1, \"b\": 2, \"c\": {\"d\": 3}}, {\"a\": 7, \"c\": {\"d\": 4, \"e\": 5}})` will result in `{\"a\": 7, \"b\": 2, \"c\": {\"d\": 4, \"e\": 5}}`.", 1466 Decl: types.NewFunction( 1467 types.Args( 1468 types.Named("a", types.NewObject( 1469 nil, 1470 types.NewDynamicProperty(types.A, types.A), 1471 )), 1472 types.Named("b", types.NewObject( 1473 nil, 1474 types.NewDynamicProperty(types.A, types.A), 1475 )), 1476 ), 1477 types.Named("output", types.A).Description("a new object which is the result of an asymmetric recursive union of two objects where conflicts are resolved by choosing the key from the right-hand object `b`"), 1478 ), // TODO(sr): types.A? ^^^^^^^ (also below) 1479 } 1480 1481 var ObjectUnionN = &Builtin{ 1482 Name: "object.union_n", 1483 Description: "Creates a new object that is the asymmetric union of all objects merged from left to right. " + 1484 "For example: `object.union_n([{\"a\": 1}, {\"b\": 2}, {\"a\": 3}])` will result in `{\"b\": 2, \"a\": 3}`.", 1485 Decl: types.NewFunction( 1486 types.Args( 1487 types.Named("objects", types.NewArray( 1488 nil, 1489 types.NewObject(nil, types.NewDynamicProperty(types.A, types.A)), 1490 )), 1491 ), 1492 types.Named("output", types.A).Description("asymmetric recursive union of all objects in `objects`, merged from left to right, where conflicts are resolved by choosing the key from the right-hand object"), 1493 ), 1494 } 1495 1496 var ObjectRemove = &Builtin{ 1497 Name: "object.remove", 1498 Description: "Removes specified keys from an object.", 1499 Decl: types.NewFunction( 1500 types.Args( 1501 types.Named("object", types.NewObject( 1502 nil, 1503 types.NewDynamicProperty(types.A, types.A), 1504 )).Description("object to remove keys from"), 1505 types.Named("keys", types.NewAny( 1506 types.NewArray(nil, types.A), 1507 types.NewSet(types.A), 1508 types.NewObject(nil, types.NewDynamicProperty(types.A, types.A)), 1509 )).Description("keys to remove from x"), 1510 ), 1511 types.Named("output", types.A).Description("result of removing the specified `keys` from `object`"), 1512 ), 1513 } 1514 1515 var ObjectFilter = &Builtin{ 1516 Name: "object.filter", 1517 Description: "Filters the object by keeping only specified keys. " + 1518 "For example: `object.filter({\"a\": {\"b\": \"x\", \"c\": \"y\"}, \"d\": \"z\"}, [\"a\"])` will result in `{\"a\": {\"b\": \"x\", \"c\": \"y\"}}`).", 1519 Decl: types.NewFunction( 1520 types.Args( 1521 types.Named("object", types.NewObject( 1522 nil, 1523 types.NewDynamicProperty(types.A, types.A), 1524 )).Description("object to filter keys"), 1525 types.Named("keys", types.NewAny( 1526 types.NewArray(nil, types.A), 1527 types.NewSet(types.A), 1528 types.NewObject(nil, types.NewDynamicProperty(types.A, types.A)), 1529 )), 1530 ), 1531 types.Named("filtered", types.A).Description("remaining data from `object` with only keys specified in `keys`"), 1532 ), 1533 } 1534 1535 var ObjectGet = &Builtin{ 1536 Name: "object.get", 1537 Description: "Returns value of an object's key if present, otherwise a default. " + 1538 "If the supplied `key` is an `array`, then `object.get` will search through a nested object or array using each key in turn. " + 1539 "For example: `object.get({\"a\": [{ \"b\": true }]}, [\"a\", 0, \"b\"], false)` results in `true`.", 1540 Decl: types.NewFunction( 1541 types.Args( 1542 types.Named("object", types.NewObject(nil, types.NewDynamicProperty(types.A, types.A))).Description("object to get `key` from"), 1543 types.Named("key", types.A).Description("key to lookup in `object`"), 1544 types.Named("default", types.A).Description("default to use when lookup fails"), 1545 ), 1546 types.Named("value", types.A).Description("`object[key]` if present, otherwise `default`"), 1547 ), 1548 } 1549 1550 /* 1551 * Encoding 1552 */ 1553 var encoding = category("encoding") 1554 1555 var JSONMarshal = &Builtin{ 1556 Name: "json.marshal", 1557 Description: "Serializes the input term to JSON.", 1558 Decl: types.NewFunction( 1559 types.Args( 1560 types.Named("x", types.A).Description("the term to serialize"), 1561 ), 1562 types.Named("y", types.S).Description("the JSON string representation of `x`"), 1563 ), 1564 Categories: encoding, 1565 } 1566 1567 var JSONUnmarshal = &Builtin{ 1568 Name: "json.unmarshal", 1569 Description: "Deserializes the input string.", 1570 Decl: types.NewFunction( 1571 types.Args( 1572 types.Named("x", types.S).Description("a JSON string"), 1573 ), 1574 types.Named("y", types.A).Description("the term deseralized from `x`"), 1575 ), 1576 Categories: encoding, 1577 } 1578 1579 var JSONIsValid = &Builtin{ 1580 Name: "json.is_valid", 1581 Description: "Verifies the input string is a valid JSON document.", 1582 Decl: types.NewFunction( 1583 types.Args( 1584 types.Named("x", types.S).Description("a JSON string"), 1585 ), 1586 types.Named("result", types.B).Description("`true` if `x` is valid JSON, `false` otherwise"), 1587 ), 1588 Categories: encoding, 1589 } 1590 1591 var Base64Encode = &Builtin{ 1592 Name: "base64.encode", 1593 Description: "Serializes the input string into base64 encoding.", 1594 Decl: types.NewFunction( 1595 types.Args( 1596 types.Named("x", types.S), 1597 ), 1598 types.Named("y", types.S).Description("base64 serialization of `x`"), 1599 ), 1600 Categories: encoding, 1601 } 1602 1603 var Base64Decode = &Builtin{ 1604 Name: "base64.decode", 1605 Description: "Deserializes the base64 encoded input string.", 1606 Decl: types.NewFunction( 1607 types.Args( 1608 types.Named("x", types.S), 1609 ), 1610 types.Named("y", types.S).Description("base64 deserialization of `x`"), 1611 ), 1612 Categories: encoding, 1613 } 1614 1615 var Base64IsValid = &Builtin{ 1616 Name: "base64.is_valid", 1617 Description: "Verifies the input string is base64 encoded.", 1618 Decl: types.NewFunction( 1619 types.Args( 1620 types.Named("x", types.S), 1621 ), 1622 types.Named("result", types.B).Description("`true` if `x` is valid base64 encoded value, `false` otherwise"), 1623 ), 1624 Categories: encoding, 1625 } 1626 1627 var Base64UrlEncode = &Builtin{ 1628 Name: "base64url.encode", 1629 Description: "Serializes the input string into base64url encoding.", 1630 Decl: types.NewFunction( 1631 types.Args( 1632 types.Named("x", types.S), 1633 ), 1634 types.Named("y", types.S).Description("base64url serialization of `x`"), 1635 ), 1636 Categories: encoding, 1637 } 1638 1639 var Base64UrlEncodeNoPad = &Builtin{ 1640 Name: "base64url.encode_no_pad", 1641 Description: "Serializes the input string into base64url encoding without padding.", 1642 Decl: types.NewFunction( 1643 types.Args( 1644 types.Named("x", types.S), 1645 ), 1646 types.Named("y", types.S).Description("base64url serialization of `x`"), 1647 ), 1648 Categories: encoding, 1649 } 1650 1651 var Base64UrlDecode = &Builtin{ 1652 Name: "base64url.decode", 1653 Description: "Deserializes the base64url encoded input string.", 1654 Decl: types.NewFunction( 1655 types.Args( 1656 types.Named("x", types.S), 1657 ), 1658 types.Named("y", types.S).Description("base64url deserialization of `x`"), 1659 ), 1660 Categories: encoding, 1661 } 1662 1663 var URLQueryDecode = &Builtin{ 1664 Name: "urlquery.decode", 1665 Description: "Decodes a URL-encoded input string.", 1666 Decl: types.NewFunction( 1667 types.Args( 1668 types.Named("x", types.S), 1669 ), 1670 types.Named("y", types.S).Description("URL-encoding deserialization of `x`"), 1671 ), 1672 Categories: encoding, 1673 } 1674 1675 var URLQueryEncode = &Builtin{ 1676 Name: "urlquery.encode", 1677 Description: "Encodes the input string into a URL-encoded string.", 1678 Decl: types.NewFunction( 1679 types.Args( 1680 types.Named("x", types.S), 1681 ), 1682 types.Named("y", types.S).Description("URL-encoding serialization of `x`"), 1683 ), 1684 Categories: encoding, 1685 } 1686 1687 var URLQueryEncodeObject = &Builtin{ 1688 Name: "urlquery.encode_object", 1689 Description: "Encodes the given object into a URL encoded query string.", 1690 Decl: types.NewFunction( 1691 types.Args( 1692 types.Named("object", types.NewObject( 1693 nil, 1694 types.NewDynamicProperty( 1695 types.S, 1696 types.NewAny( 1697 types.S, 1698 types.NewArray(nil, types.S), 1699 types.NewSet(types.S)))))), 1700 types.Named("y", types.S).Description("the URL-encoded serialization of `object`"), 1701 ), 1702 Categories: encoding, 1703 } 1704 1705 var URLQueryDecodeObject = &Builtin{ 1706 Name: "urlquery.decode_object", 1707 Description: "Decodes the given URL query string into an object.", 1708 Decl: types.NewFunction( 1709 types.Args( 1710 types.Named("x", types.S).Description("the query string"), 1711 ), 1712 types.Named("object", types.NewObject(nil, types.NewDynamicProperty( 1713 types.S, 1714 types.NewArray(nil, types.S)))).Description("the resulting object"), 1715 ), 1716 Categories: encoding, 1717 } 1718 1719 var YAMLMarshal = &Builtin{ 1720 Name: "yaml.marshal", 1721 Description: "Serializes the input term to YAML.", 1722 Decl: types.NewFunction( 1723 types.Args( 1724 types.Named("x", types.A).Description("the term to serialize"), 1725 ), 1726 types.Named("y", types.S).Description("the YAML string representation of `x`"), 1727 ), 1728 Categories: encoding, 1729 } 1730 1731 var YAMLUnmarshal = &Builtin{ 1732 Name: "yaml.unmarshal", 1733 Description: "Deserializes the input string.", 1734 Decl: types.NewFunction( 1735 types.Args( 1736 types.Named("x", types.S).Description("a YAML string"), 1737 ), 1738 types.Named("y", types.A).Description("the term deseralized from `x`"), 1739 ), 1740 Categories: encoding, 1741 } 1742 1743 // YAMLIsValid verifies the input string is a valid YAML document. 1744 var YAMLIsValid = &Builtin{ 1745 Name: "yaml.is_valid", 1746 Description: "Verifies the input string is a valid YAML document.", 1747 Decl: types.NewFunction( 1748 types.Args( 1749 types.Named("x", types.S).Description("a YAML string"), 1750 ), 1751 types.Named("result", types.B).Description("`true` if `x` is valid YAML, `false` otherwise"), 1752 ), 1753 Categories: encoding, 1754 } 1755 1756 var HexEncode = &Builtin{ 1757 Name: "hex.encode", 1758 Description: "Serializes the input string using hex-encoding.", 1759 Decl: types.NewFunction( 1760 types.Args( 1761 types.Named("x", types.S), 1762 ), 1763 types.Named("y", types.S).Description("serialization of `x` using hex-encoding"), 1764 ), 1765 Categories: encoding, 1766 } 1767 1768 var HexDecode = &Builtin{ 1769 Name: "hex.decode", 1770 Description: "Deserializes the hex-encoded input string.", 1771 Decl: types.NewFunction( 1772 types.Args( 1773 types.Named("x", types.S).Description("a hex-encoded string"), 1774 ), 1775 types.Named("y", types.S).Description("deseralized from `x`"), 1776 ), 1777 Categories: encoding, 1778 } 1779 1780 /** 1781 * Tokens 1782 */ 1783 var tokensCat = category("tokens") 1784 1785 var JWTDecode = &Builtin{ 1786 Name: "io.jwt.decode", 1787 Description: "Decodes a JSON Web Token and outputs it as an object.", 1788 Decl: types.NewFunction( 1789 types.Args( 1790 types.Named("jwt", types.S).Description("JWT token to decode"), 1791 ), 1792 types.Named("output", types.NewArray([]types.Type{ 1793 types.NewObject(nil, types.NewDynamicProperty(types.A, types.A)), 1794 types.NewObject(nil, types.NewDynamicProperty(types.A, types.A)), 1795 types.S, 1796 }, nil)).Description("`[header, payload, sig]`, where `header` and `payload` are objects; `sig` is the hexadecimal representation of the signature on the token."), 1797 ), 1798 Categories: tokensCat, 1799 } 1800 1801 var JWTVerifyRS256 = &Builtin{ 1802 Name: "io.jwt.verify_rs256", 1803 Description: "Verifies if a RS256 JWT signature is valid.", 1804 Decl: types.NewFunction( 1805 types.Args( 1806 types.Named("jwt", types.S).Description("JWT token whose signature is to be verified"), 1807 types.Named("certificate", types.S).Description("PEM encoded certificate, PEM encoded public key, or the JWK key (set) used to verify the signature"), 1808 ), 1809 types.Named("result", types.B).Description("`true` if the signature is valid, `false` otherwise"), 1810 ), 1811 Categories: tokensCat, 1812 } 1813 1814 var JWTVerifyRS384 = &Builtin{ 1815 Name: "io.jwt.verify_rs384", 1816 Description: "Verifies if a RS384 JWT signature is valid.", 1817 Decl: types.NewFunction( 1818 types.Args( 1819 types.Named("jwt", types.S).Description("JWT token whose signature is to be verified"), 1820 types.Named("certificate", types.S).Description("PEM encoded certificate, PEM encoded public key, or the JWK key (set) used to verify the signature"), 1821 ), 1822 types.Named("result", types.B).Description("`true` if the signature is valid, `false` otherwise"), 1823 ), 1824 Categories: tokensCat, 1825 } 1826 1827 var JWTVerifyRS512 = &Builtin{ 1828 Name: "io.jwt.verify_rs512", 1829 Description: "Verifies if a RS512 JWT signature is valid.", 1830 Decl: types.NewFunction( 1831 types.Args( 1832 types.Named("jwt", types.S).Description("JWT token whose signature is to be verified"), 1833 types.Named("certificate", types.S).Description("PEM encoded certificate, PEM encoded public key, or the JWK key (set) used to verify the signature"), 1834 ), 1835 types.Named("result", types.B).Description("`true` if the signature is valid, `false` otherwise"), 1836 ), 1837 Categories: tokensCat, 1838 } 1839 1840 var JWTVerifyPS256 = &Builtin{ 1841 Name: "io.jwt.verify_ps256", 1842 Description: "Verifies if a PS256 JWT signature is valid.", 1843 Decl: types.NewFunction( 1844 types.Args( 1845 types.Named("jwt", types.S).Description("JWT token whose signature is to be verified"), 1846 types.Named("certificate", types.S).Description("PEM encoded certificate, PEM encoded public key, or the JWK key (set) used to verify the signature"), 1847 ), 1848 types.Named("result", types.B).Description("`true` if the signature is valid, `false` otherwise"), 1849 ), 1850 Categories: tokensCat, 1851 } 1852 1853 var JWTVerifyPS384 = &Builtin{ 1854 Name: "io.jwt.verify_ps384", 1855 Description: "Verifies if a PS384 JWT signature is valid.", 1856 Decl: types.NewFunction( 1857 types.Args( 1858 types.Named("jwt", types.S).Description("JWT token whose signature is to be verified"), 1859 types.Named("certificate", types.S).Description("PEM encoded certificate, PEM encoded public key, or the JWK key (set) used to verify the signature"), 1860 ), 1861 types.Named("result", types.B).Description("`true` if the signature is valid, `false` otherwise"), 1862 ), 1863 Categories: tokensCat, 1864 } 1865 1866 var JWTVerifyPS512 = &Builtin{ 1867 Name: "io.jwt.verify_ps512", 1868 Description: "Verifies if a PS512 JWT signature is valid.", 1869 Decl: types.NewFunction( 1870 types.Args( 1871 types.Named("jwt", types.S).Description("JWT token whose signature is to be verified"), 1872 types.Named("certificate", types.S).Description("PEM encoded certificate, PEM encoded public key, or the JWK key (set) used to verify the signature"), 1873 ), 1874 types.Named("result", types.B).Description("`true` if the signature is valid, `false` otherwise"), 1875 ), 1876 Categories: tokensCat, 1877 } 1878 1879 var JWTVerifyES256 = &Builtin{ 1880 Name: "io.jwt.verify_es256", 1881 Description: "Verifies if a ES256 JWT signature is valid.", 1882 Decl: types.NewFunction( 1883 types.Args( 1884 types.Named("jwt", types.S).Description("JWT token whose signature is to be verified"), 1885 types.Named("certificate", types.S).Description("PEM encoded certificate, PEM encoded public key, or the JWK key (set) used to verify the signature"), 1886 ), 1887 types.Named("result", types.B).Description("`true` if the signature is valid, `false` otherwise"), 1888 ), 1889 Categories: tokensCat, 1890 } 1891 1892 var JWTVerifyES384 = &Builtin{ 1893 Name: "io.jwt.verify_es384", 1894 Description: "Verifies if a ES384 JWT signature is valid.", 1895 Decl: types.NewFunction( 1896 types.Args( 1897 types.Named("jwt", types.S).Description("JWT token whose signature is to be verified"), 1898 types.Named("certificate", types.S).Description("PEM encoded certificate, PEM encoded public key, or the JWK key (set) used to verify the signature"), 1899 ), 1900 types.Named("result", types.B).Description("`true` if the signature is valid, `false` otherwise"), 1901 ), 1902 Categories: tokensCat, 1903 } 1904 1905 var JWTVerifyES512 = &Builtin{ 1906 Name: "io.jwt.verify_es512", 1907 Description: "Verifies if a ES512 JWT signature is valid.", 1908 Decl: types.NewFunction( 1909 types.Args( 1910 types.Named("jwt", types.S).Description("JWT token whose signature is to be verified"), 1911 types.Named("certificate", types.S).Description("PEM encoded certificate, PEM encoded public key, or the JWK key (set) used to verify the signature"), 1912 ), 1913 types.Named("result", types.B).Description("`true` if the signature is valid, `false` otherwise"), 1914 ), 1915 Categories: tokensCat, 1916 } 1917 1918 var JWTVerifyHS256 = &Builtin{ 1919 Name: "io.jwt.verify_hs256", 1920 Description: "Verifies if a HS256 (secret) JWT signature is valid.", 1921 Decl: types.NewFunction( 1922 types.Args( 1923 types.Named("jwt", types.S).Description("JWT token whose signature is to be verified"), 1924 types.Named("secret", types.S).Description("plain text secret used to verify the signature"), 1925 ), 1926 types.Named("result", types.B).Description("`true` if the signature is valid, `false` otherwise"), 1927 ), 1928 Categories: tokensCat, 1929 } 1930 1931 var JWTVerifyHS384 = &Builtin{ 1932 Name: "io.jwt.verify_hs384", 1933 Description: "Verifies if a HS384 (secret) JWT signature is valid.", 1934 Decl: types.NewFunction( 1935 types.Args( 1936 types.Named("jwt", types.S).Description("JWT token whose signature is to be verified"), 1937 types.Named("secret", types.S).Description("plain text secret used to verify the signature"), 1938 ), 1939 types.Named("result", types.B).Description("`true` if the signature is valid, `false` otherwise"), 1940 ), 1941 Categories: tokensCat, 1942 } 1943 1944 var JWTVerifyHS512 = &Builtin{ 1945 Name: "io.jwt.verify_hs512", 1946 Description: "Verifies if a HS512 (secret) JWT signature is valid.", 1947 Decl: types.NewFunction( 1948 types.Args( 1949 types.Named("jwt", types.S).Description("JWT token whose signature is to be verified"), 1950 types.Named("secret", types.S).Description("plain text secret used to verify the signature"), 1951 ), 1952 types.Named("result", types.B).Description("`true` if the signature is valid, `false` otherwise"), 1953 ), 1954 Categories: tokensCat, 1955 } 1956 1957 var JWTDecodeVerify = &Builtin{ 1958 Name: "io.jwt.decode_verify", 1959 Description: `Verifies a JWT signature under parameterized constraints and decodes the claims if it is valid. 1960 Supports the following algorithms: HS256, HS384, HS512, RS256, RS384, RS512, ES256, ES384, ES512, PS256, PS384 and PS512.`, 1961 Decl: types.NewFunction( 1962 types.Args( 1963 types.Named("jwt", types.S).Description("JWT token whose signature is to be verified and whose claims are to be checked"), 1964 types.Named("constraints", types.NewObject(nil, types.NewDynamicProperty(types.S, types.A))).Description("claim verification constraints"), 1965 ), 1966 types.Named("output", types.NewArray([]types.Type{ 1967 types.B, 1968 types.NewObject(nil, types.NewDynamicProperty(types.A, types.A)), 1969 types.NewObject(nil, types.NewDynamicProperty(types.A, types.A)), 1970 }, nil)).Description("`[valid, header, payload]`: if the input token is verified and meets the requirements of `constraints` then `valid` is `true`; `header` and `payload` are objects containing the JOSE header and the JWT claim set; otherwise, `valid` is `false`, `header` and `payload` are `{}`"), 1971 ), 1972 Categories: tokensCat, 1973 } 1974 1975 var tokenSign = category("tokensign") 1976 1977 var JWTEncodeSignRaw = &Builtin{ 1978 Name: "io.jwt.encode_sign_raw", 1979 Description: "Encodes and optionally signs a JSON Web Token.", 1980 Decl: types.NewFunction( 1981 types.Args( 1982 types.Named("headers", types.S).Description("JWS Protected Header"), 1983 types.Named("payload", types.S).Description("JWS Payload"), 1984 types.Named("key", types.S).Description("JSON Web Key (RFC7517)"), 1985 ), 1986 types.Named("output", types.S).Description("signed JWT"), 1987 ), 1988 Categories: tokenSign, 1989 } 1990 1991 var JWTEncodeSign = &Builtin{ 1992 Name: "io.jwt.encode_sign", 1993 Description: "Encodes and optionally signs a JSON Web Token. Inputs are taken as objects, not encoded strings (see `io.jwt.encode_sign_raw`).", 1994 Decl: types.NewFunction( 1995 types.Args( 1996 types.Named("headers", types.NewObject(nil, types.NewDynamicProperty(types.S, types.A))).Description("JWS Protected Header"), 1997 types.Named("payload", types.NewObject(nil, types.NewDynamicProperty(types.S, types.A))).Description("JWS Payload"), 1998 types.Named("key", types.NewObject(nil, types.NewDynamicProperty(types.S, types.A))).Description("JSON Web Key (RFC7517)"), 1999 ), 2000 types.Named("output", types.S).Description("signed JWT"), 2001 ), 2002 Categories: tokenSign, 2003 } 2004 2005 /** 2006 * Time 2007 */ 2008 2009 var NowNanos = &Builtin{ 2010 Name: "time.now_ns", 2011 Description: "Returns the current time since epoch in nanoseconds.", 2012 Decl: types.NewFunction( 2013 nil, 2014 types.Named("now", types.N).Description("nanoseconds since epoch"), 2015 ), 2016 } 2017 2018 var ParseNanos = &Builtin{ 2019 Name: "time.parse_ns", 2020 Description: "Returns the time in nanoseconds parsed from the string in the given format. `undefined` if the result would be outside the valid time range that can fit within an `int64`.", 2021 Decl: types.NewFunction( 2022 types.Args( 2023 types.Named("layout", types.S).Description("format used for parsing, see the [Go `time` package documentation](https://golang.org/pkg/time/#Parse) for more details"), 2024 types.Named("value", types.S).Description("input to parse according to `layout`"), 2025 ), 2026 types.Named("ns", types.N).Description("`value` in nanoseconds since epoch"), 2027 ), 2028 } 2029 2030 var ParseRFC3339Nanos = &Builtin{ 2031 Name: "time.parse_rfc3339_ns", 2032 Description: "Returns the time in nanoseconds parsed from the string in RFC3339 format. `undefined` if the result would be outside the valid time range that can fit within an `int64`.", 2033 Decl: types.NewFunction( 2034 types.Args( 2035 types.Named("value", types.S), 2036 ), 2037 types.Named("ns", types.N).Description("`value` in nanoseconds since epoch"), 2038 ), 2039 } 2040 2041 var ParseDurationNanos = &Builtin{ 2042 Name: "time.parse_duration_ns", 2043 Description: "Returns the duration in nanoseconds represented by a string.", 2044 Decl: types.NewFunction( 2045 types.Args( 2046 types.Named("duration", types.S).Description("a duration like \"3m\"; seethe [Go `time` package documentation](https://golang.org/pkg/time/#ParseDuration) for more details"), 2047 ), 2048 types.Named("ns", types.N).Description("the `duration` in nanoseconds"), 2049 ), 2050 } 2051 2052 var Date = &Builtin{ 2053 Name: "time.date", 2054 Description: "Returns the `[year, month, day]` for the nanoseconds since epoch.", 2055 Decl: types.NewFunction( 2056 types.Args( 2057 types.Named("x", types.NewAny( 2058 types.N, 2059 types.NewArray([]types.Type{types.N, types.S}, nil), 2060 )).Description("a number representing the nanoseconds since the epoch (UTC); or a two-element array of the nanoseconds, and a timezone string"), 2061 ), 2062 types.Named("date", types.NewArray([]types.Type{types.N, types.N, types.N}, nil)).Description("an array of `year`, `month` (1-12), and `day` (1-31)"), 2063 ), 2064 } 2065 2066 var Clock = &Builtin{ 2067 Name: "time.clock", 2068 Description: "Returns the `[hour, minute, second]` of the day for the nanoseconds since epoch.", 2069 Decl: types.NewFunction( 2070 types.Args( 2071 types.Named("x", types.NewAny( 2072 types.N, 2073 types.NewArray([]types.Type{types.N, types.S}, nil), 2074 )).Description("a number representing the nanoseconds since the epoch (UTC); or a two-element array of the nanoseconds, and a timezone string"), 2075 ), 2076 types.Named("output", types.NewArray([]types.Type{types.N, types.N, types.N}, nil)). 2077 Description("the `hour`, `minute` (0-59), and `second` (0-59) representing the time of day for the nanoseconds since epoch in the supplied timezone (or UTC)"), 2078 ), 2079 } 2080 2081 var Weekday = &Builtin{ 2082 Name: "time.weekday", 2083 Description: "Returns the day of the week (Monday, Tuesday, ...) for the nanoseconds since epoch.", 2084 Decl: types.NewFunction( 2085 types.Args( 2086 types.Named("x", types.NewAny( 2087 types.N, 2088 types.NewArray([]types.Type{types.N, types.S}, nil), 2089 )).Description("a number representing the nanoseconds since the epoch (UTC); or a two-element array of the nanoseconds, and a timezone string"), 2090 ), 2091 types.Named("day", types.S).Description("the weekday represented by `ns` nanoseconds since the epoch in the supplied timezone (or UTC)"), 2092 ), 2093 } 2094 2095 var AddDate = &Builtin{ 2096 Name: "time.add_date", 2097 Description: "Returns the nanoseconds since epoch after adding years, months and days to nanoseconds. `undefined` if the result would be outside the valid time range that can fit within an `int64`.", 2098 Decl: types.NewFunction( 2099 types.Args( 2100 types.Named("ns", types.N).Description("nanoseconds since the epoch"), 2101 types.Named("years", types.N), 2102 types.Named("months", types.N), 2103 types.Named("days", types.N), 2104 ), 2105 types.Named("output", types.N).Description("nanoseconds since the epoch representing the input time, with years, months and days added"), 2106 ), 2107 } 2108 2109 var Diff = &Builtin{ 2110 Name: "time.diff", 2111 Description: "Returns the difference between two unix timestamps in nanoseconds (with optional timezone strings).", 2112 Decl: types.NewFunction( 2113 types.Args( 2114 types.Named("ns1", types.NewAny( 2115 types.N, 2116 types.NewArray([]types.Type{types.N, types.S}, nil), 2117 )), 2118 types.Named("ns2", types.NewAny( 2119 types.N, 2120 types.NewArray([]types.Type{types.N, types.S}, nil), 2121 )), 2122 ), 2123 types.Named("output", types.NewArray([]types.Type{types.N, types.N, types.N, types.N, types.N, types.N}, nil)).Description("difference between `ns1` and `ns2` (in their supplied timezones, if supplied, or UTC) as array of numbers: `[years, months, days, hours, minutes, seconds]`"), 2124 ), 2125 } 2126 2127 /** 2128 * Crypto. 2129 */ 2130 2131 var CryptoX509ParseCertificates = &Builtin{ 2132 Name: "crypto.x509.parse_certificates", 2133 Description: "Returns one or more certificates from the given base64 encoded string containing DER encoded certificates that have been concatenated.", 2134 Decl: types.NewFunction( 2135 types.Args( 2136 types.Named("certs", types.S).Description("base64 encoded DER or PEM data containing one or more certificates or a PEM string of one or more certificates"), 2137 ), 2138 types.Named("output", types.NewArray(nil, types.NewObject(nil, types.NewDynamicProperty(types.S, types.A)))).Description("parsed X.509 certificates represented as objects"), 2139 ), 2140 } 2141 2142 var CryptoX509ParseAndVerifyCertificates = &Builtin{ 2143 Name: "crypto.x509.parse_and_verify_certificates", 2144 Description: `Returns one or more certificates from the given string containing PEM 2145 or base64 encoded DER certificates after verifying the supplied certificates form a complete 2146 certificate chain back to a trusted root. 2147 2148 The first certificate is treated as the root and the last is treated as the leaf, 2149 with all others being treated as intermediates.`, 2150 Decl: types.NewFunction( 2151 types.Args( 2152 types.Named("certs", types.S).Description("base64 encoded DER or PEM data containing two or more certificates where the first is a root CA, the last is a leaf certificate, and all others are intermediate CAs"), 2153 ), 2154 types.Named("output", types.NewArray([]types.Type{ 2155 types.B, 2156 types.NewArray(nil, types.NewObject(nil, types.NewDynamicProperty(types.S, types.A))), 2157 }, nil)).Description("array of `[valid, certs]`: if the input certificate chain could be verified then `valid` is `true` and `certs` is an array of X.509 certificates represented as objects; if the input certificate chain could not be verified then `valid` is `false` and `certs` is `[]`"), 2158 ), 2159 } 2160 2161 var CryptoX509ParseCertificateRequest = &Builtin{ 2162 Name: "crypto.x509.parse_certificate_request", 2163 Description: "Returns a PKCS #10 certificate signing request from the given PEM-encoded PKCS#10 certificate signing request.", 2164 Decl: types.NewFunction( 2165 types.Args( 2166 types.Named("csr", types.S).Description("base64 string containing either a PEM encoded or DER CSR or a string containing a PEM CSR"), 2167 ), 2168 types.Named("output", types.NewObject(nil, types.NewDynamicProperty(types.S, types.A))).Description("X.509 CSR represented as an object"), 2169 ), 2170 } 2171 2172 var CryptoX509ParseRSAPrivateKey = &Builtin{ 2173 Name: "crypto.x509.parse_rsa_private_key", 2174 Description: "Returns a JWK for signing a JWT from the given PEM-encoded RSA private key.", 2175 Decl: types.NewFunction( 2176 types.Args( 2177 types.Named("pem", types.S).Description("base64 string containing a PEM encoded RSA private key"), 2178 ), 2179 types.Named("output", types.NewObject(nil, types.NewDynamicProperty(types.S, types.A))).Description("JWK as an object"), 2180 ), 2181 } 2182 2183 var CryptoMd5 = &Builtin{ 2184 Name: "crypto.md5", 2185 Description: "Returns a string representing the input string hashed with the MD5 function", 2186 Decl: types.NewFunction( 2187 types.Args( 2188 types.Named("x", types.S), 2189 ), 2190 types.Named("y", types.S).Description("MD5-hash of `x`"), 2191 ), 2192 } 2193 2194 var CryptoSha1 = &Builtin{ 2195 Name: "crypto.sha1", 2196 Description: "Returns a string representing the input string hashed with the SHA1 function", 2197 Decl: types.NewFunction( 2198 types.Args( 2199 types.Named("x", types.S), 2200 ), 2201 types.Named("y", types.S).Description("SHA1-hash of `x`"), 2202 ), 2203 } 2204 2205 var CryptoSha256 = &Builtin{ 2206 Name: "crypto.sha256", 2207 Description: "Returns a string representing the input string hashed with the SHA256 function", 2208 Decl: types.NewFunction( 2209 types.Args( 2210 types.Named("x", types.S), 2211 ), 2212 types.Named("y", types.S).Description("SHA256-hash of `x`"), 2213 ), 2214 } 2215 2216 var CryptoHmacMd5 = &Builtin{ 2217 Name: "crypto.hmac.md5", 2218 Description: "Returns a string representing the MD5 HMAC of the input message using the input key.", 2219 Decl: types.NewFunction( 2220 types.Args( 2221 types.Named("x", types.S).Description("input string"), 2222 types.Named("key", types.S).Description("key to use"), 2223 ), 2224 types.Named("y", types.S).Description("MD5-HMAC of `x`"), 2225 ), 2226 } 2227 2228 var CryptoHmacSha1 = &Builtin{ 2229 Name: "crypto.hmac.sha1", 2230 Description: "Returns a string representing the SHA1 HMAC of the input message using the input key.", 2231 Decl: types.NewFunction( 2232 types.Args( 2233 types.Named("x", types.S).Description("input string"), 2234 types.Named("key", types.S).Description("key to use"), 2235 ), 2236 types.Named("y", types.S).Description("SHA1-HMAC of `x`"), 2237 ), 2238 } 2239 2240 var CryptoHmacSha256 = &Builtin{ 2241 Name: "crypto.hmac.sha256", 2242 Description: "Returns a string representing the SHA256 HMAC of the input message using the input key.", 2243 Decl: types.NewFunction( 2244 types.Args( 2245 types.Named("x", types.S).Description("input string"), 2246 types.Named("key", types.S).Description("key to use"), 2247 ), 2248 types.Named("y", types.S).Description("SHA256-HMAC of `x`"), 2249 ), 2250 } 2251 2252 var CryptoHmacSha512 = &Builtin{ 2253 Name: "crypto.hmac.sha512", 2254 Description: "Returns a string representing the SHA512 HMAC of the input message using the input key.", 2255 Decl: types.NewFunction( 2256 types.Args( 2257 types.Named("x", types.S).Description("input string"), 2258 types.Named("key", types.S).Description("key to use"), 2259 ), 2260 types.Named("y", types.S).Description("SHA512-HMAC of `x`"), 2261 ), 2262 } 2263 2264 /** 2265 * Graphs. 2266 */ 2267 var graphs = category("graph") 2268 2269 var WalkBuiltin = &Builtin{ 2270 Name: "walk", 2271 Relation: true, 2272 Description: "Generates `[path, value]` tuples for all nested documents of `x` (recursively). Queries can use `walk` to traverse documents nested under `x`.", 2273 Decl: types.NewFunction( 2274 types.Args( 2275 types.Named("x", types.A), 2276 ), 2277 types.Named("output", types.NewArray( 2278 []types.Type{ 2279 types.NewArray(nil, types.A), 2280 types.A, 2281 }, 2282 nil, 2283 )).Description("pairs of `path` and `value`: `path` is an array representing the pointer to `value` in `x`"), 2284 ), 2285 Categories: graphs, 2286 } 2287 2288 var ReachableBuiltin = &Builtin{ 2289 Name: "graph.reachable", 2290 Description: "Computes the set of reachable nodes in the graph from a set of starting nodes.", 2291 Decl: types.NewFunction( 2292 types.Args( 2293 types.Named("graph", types.NewObject( 2294 nil, 2295 types.NewDynamicProperty( 2296 types.A, 2297 types.NewAny( 2298 types.NewSet(types.A), 2299 types.NewArray(nil, types.A)), 2300 )), 2301 ).Description("object containing a set or array of neighboring vertices"), 2302 types.Named("initial", types.NewAny(types.NewSet(types.A), types.NewArray(nil, types.A))).Description("set or array of root vertices"), 2303 ), 2304 types.Named("output", types.NewSet(types.A)).Description("set of vertices reachable from the `initial` vertices in the directed `graph`"), 2305 ), 2306 } 2307 2308 var ReachablePathsBuiltin = &Builtin{ 2309 Name: "graph.reachable_paths", 2310 Description: "Computes the set of reachable paths in the graph from a set of starting nodes.", 2311 Decl: types.NewFunction( 2312 types.Args( 2313 types.Named("graph", types.NewObject( 2314 nil, 2315 types.NewDynamicProperty( 2316 types.A, 2317 types.NewAny( 2318 types.NewSet(types.A), 2319 types.NewArray(nil, types.A)), 2320 )), 2321 ).Description("object containing a set or array of root vertices"), 2322 types.Named("initial", types.NewAny(types.NewSet(types.A), types.NewArray(nil, types.A))).Description("initial paths"), // TODO(sr): copied. is that correct? 2323 ), 2324 types.Named("output", types.NewSet(types.NewArray(nil, types.A))).Description("paths reachable from the `initial` vertices in the directed `graph`"), 2325 ), 2326 } 2327 2328 /** 2329 * Type 2330 */ 2331 var typesCat = category("types") 2332 2333 var IsNumber = &Builtin{ 2334 Name: "is_number", 2335 Description: "Returns `true` if the input value is a number.", 2336 Decl: types.NewFunction( 2337 types.Args( 2338 types.Named("x", types.A), 2339 ), 2340 types.Named("result", types.B).Description("`true` if `x` is a number, `false` otherwise."), 2341 ), 2342 Categories: typesCat, 2343 } 2344 2345 var IsString = &Builtin{ 2346 Name: "is_string", 2347 Description: "Returns `true` if the input value is a string.", 2348 Decl: types.NewFunction( 2349 types.Args( 2350 types.Named("x", types.A), 2351 ), 2352 types.Named("result", types.B).Description("`true` if `x` is a string, `false` otherwise."), 2353 ), 2354 Categories: typesCat, 2355 } 2356 2357 var IsBoolean = &Builtin{ 2358 Name: "is_boolean", 2359 Description: "Returns `true` if the input value is a boolean.", 2360 Decl: types.NewFunction( 2361 types.Args( 2362 types.Named("x", types.A), 2363 ), 2364 types.Named("result", types.B).Description("`true` if `x` is an boolean, `false` otherwise."), 2365 ), 2366 Categories: typesCat, 2367 } 2368 2369 var IsArray = &Builtin{ 2370 Name: "is_array", 2371 Description: "Returns `true` if the input value is an array.", 2372 Decl: types.NewFunction( 2373 types.Args( 2374 types.Named("x", types.A), 2375 ), 2376 types.Named("result", types.B).Description("`true` if `x` is an array, `false` otherwise."), 2377 ), 2378 Categories: typesCat, 2379 } 2380 2381 var IsSet = &Builtin{ 2382 Name: "is_set", 2383 Description: "Returns `true` if the input value is a set.", 2384 Decl: types.NewFunction( 2385 types.Args( 2386 types.Named("x", types.A), 2387 ), 2388 types.Named("result", types.B).Description("`true` if `x` is a set, `false` otherwise."), 2389 ), 2390 Categories: typesCat, 2391 } 2392 2393 var IsObject = &Builtin{ 2394 Name: "is_object", 2395 Description: "Returns true if the input value is an object", 2396 Decl: types.NewFunction( 2397 types.Args( 2398 types.Named("x", types.A), 2399 ), 2400 types.Named("result", types.B).Description("`true` if `x` is an object, `false` otherwise."), 2401 ), 2402 Categories: typesCat, 2403 } 2404 2405 var IsNull = &Builtin{ 2406 Name: "is_null", 2407 Description: "Returns `true` if the input value is null.", 2408 Decl: types.NewFunction( 2409 types.Args( 2410 types.Named("x", types.A), 2411 ), 2412 types.Named("result", types.B).Description("`true` if `x` is null, `false` otherwise."), 2413 ), 2414 Categories: typesCat, 2415 } 2416 2417 /** 2418 * Type Name 2419 */ 2420 2421 // TypeNameBuiltin returns the type of the input. 2422 var TypeNameBuiltin = &Builtin{ 2423 Name: "type_name", 2424 Decl: types.NewFunction( 2425 types.Args( 2426 types.NewAny( 2427 types.A, 2428 ), 2429 ), 2430 types.S, 2431 ), 2432 } 2433 2434 /** 2435 * HTTP Request 2436 */ 2437 2438 var HTTPSend = &Builtin{ 2439 Name: "http.send", 2440 Description: "Returns a HTTP response to the given HTTP request.", 2441 Decl: types.NewFunction( 2442 types.Args( 2443 types.Named("request", types.NewObject(nil, types.NewDynamicProperty(types.S, types.A))), 2444 ), 2445 types.Named("response", types.NewObject(nil, types.NewDynamicProperty(types.A, types.A))), 2446 ), 2447 } 2448 2449 /** 2450 * GraphQL 2451 */ 2452 2453 // GraphQLParse returns a pair of AST objects from parsing/validation. 2454 var GraphQLParse = &Builtin{ 2455 Name: "graphql.parse", 2456 Description: "Returns AST objects for a given GraphQL query and schema after validating the query against the schema. Returns undefined if errors were encountered during parsing or validation.", 2457 Decl: types.NewFunction( 2458 types.Args( 2459 types.Named("query", types.S), 2460 types.Named("schema", types.S), 2461 ), 2462 types.Named("output", types.NewArray([]types.Type{ 2463 types.NewObject(nil, types.NewDynamicProperty(types.A, types.A)), 2464 types.NewObject(nil, types.NewDynamicProperty(types.A, types.A)), 2465 }, nil)).Description("`output` is of the form `[query_ast, schema_ast]`. If the GraphQL query is valid given the provided schema, then `query_ast` and `schema_ast` are objects describing the ASTs for the query and schema."), 2466 ), 2467 } 2468 2469 // GraphQLParseAndVerify returns a boolean and a pair of AST object from parsing/validation. 2470 var GraphQLParseAndVerify = &Builtin{ 2471 Name: "graphql.parse_and_verify", 2472 Description: "Returns a boolean indicating success or failure alongside the parsed ASTs for a given GraphQL query and schema after validating the query against the schema.", 2473 Decl: types.NewFunction( 2474 types.Args( 2475 types.Named("query", types.S), 2476 types.Named("schema", types.S), 2477 ), 2478 types.Named("output", types.NewArray([]types.Type{ 2479 types.B, 2480 types.NewObject(nil, types.NewDynamicProperty(types.A, types.A)), 2481 types.NewObject(nil, types.NewDynamicProperty(types.A, types.A)), 2482 }, nil)).Description(" `output` is of the form `[valid, query_ast, schema_ast]`. If the query is valid given the provided schema, then `valid` is `true`, and `query_ast` and `schema_ast` are objects describing the ASTs for the GraphQL query and schema. Otherwise, `valid` is `false` and `query_ast` and `schema_ast` are `{}`."), 2483 ), 2484 } 2485 2486 // GraphQLParseQuery parses the input GraphQL query and returns a JSON 2487 // representation of its AST. 2488 var GraphQLParseQuery = &Builtin{ 2489 Name: "graphql.parse_query", 2490 Description: "Returns an AST object for a GraphQL query.", 2491 Decl: types.NewFunction( 2492 types.Args( 2493 types.Named("query", types.S), 2494 ), 2495 types.Named("output", types.NewObject(nil, types.NewDynamicProperty(types.A, types.A))).Description("AST object for the GraphQL query."), 2496 ), 2497 } 2498 2499 // GraphQLParseSchema parses the input GraphQL schema and returns a JSON 2500 // representation of its AST. 2501 var GraphQLParseSchema = &Builtin{ 2502 Name: "graphql.parse_schema", 2503 Description: "Returns an AST object for a GraphQL schema.", 2504 Decl: types.NewFunction( 2505 types.Args( 2506 types.Named("schema", types.S), 2507 ), 2508 types.Named("output", types.NewObject(nil, types.NewDynamicProperty(types.A, types.A))).Description("AST object for the GraphQL schema."), 2509 ), 2510 } 2511 2512 // GraphQLIsValid returns true if a GraphQL query is valid with a given 2513 // schema, and returns false for all other inputs. 2514 var GraphQLIsValid = &Builtin{ 2515 Name: "graphql.is_valid", 2516 Description: "Checks that a GraphQL query is valid against a given schema.", 2517 Decl: types.NewFunction( 2518 types.Args( 2519 types.Named("query", types.S), 2520 types.Named("schema", types.S), 2521 ), 2522 types.Named("output", types.B).Description("`true` if the query is valid under the given schema. `false` otherwise."), 2523 ), 2524 } 2525 2526 /** 2527 * Rego 2528 */ 2529 2530 var RegoParseModule = &Builtin{ 2531 Name: "rego.parse_module", 2532 Description: "Parses the input Rego string and returns an object representation of the AST.", 2533 Decl: types.NewFunction( 2534 types.Args( 2535 types.Named("filename", types.S).Description("file name to attach to AST nodes' locations"), 2536 types.Named("rego", types.S).Description("Rego module"), 2537 ), 2538 types.Named("output", types.NewObject(nil, types.NewDynamicProperty(types.S, types.A))), // TODO(tsandall): import AST schema 2539 ), 2540 } 2541 2542 var RegoMetadataChain = &Builtin{ 2543 Name: "rego.metadata.chain", 2544 Description: `Returns the chain of metadata for the active rule. 2545 Ordered starting at the active rule, going outward to the most distant node in its package ancestry. 2546 A chain entry is a JSON document with two members: "path", an array representing the path of the node; and "annotations", a JSON document containing the annotations declared for the node. 2547 The first entry in the chain always points to the active rule, even if it has no declared annotations (in which case the "annotations" member is not present).`, 2548 Decl: types.NewFunction( 2549 types.Args(), 2550 types.Named("chain", types.NewArray(nil, types.A)).Description("each array entry represents a node in the path ancestry (chain) of the active rule that also has declared annotations"), 2551 ), 2552 } 2553 2554 // RegoMetadataRule returns the metadata for the active rule 2555 var RegoMetadataRule = &Builtin{ 2556 Name: "rego.metadata.rule", 2557 Description: "Returns annotations declared for the active rule and using the _rule_ scope.", 2558 Decl: types.NewFunction( 2559 types.Args(), 2560 types.Named("output", types.A).Description("\"rule\" scope annotations for this rule; empty object if no annotations exist"), 2561 ), 2562 } 2563 2564 /** 2565 * OPA 2566 */ 2567 2568 var OPARuntime = &Builtin{ 2569 Name: "opa.runtime", 2570 Description: "Returns an object that describes the runtime environment where OPA is deployed.", 2571 Decl: types.NewFunction( 2572 nil, 2573 types.Named("output", types.NewObject(nil, types.NewDynamicProperty(types.S, types.A))). 2574 Description("includes a `config` key if OPA was started with a configuration file; an `env` key containing the environment variables that the OPA process was started with; includes `version` and `commit` keys containing the version and build commit of OPA."), 2575 ), 2576 } 2577 2578 /** 2579 * Trace 2580 */ 2581 var tracing = category("tracing") 2582 2583 var Trace = &Builtin{ 2584 Name: "trace", 2585 Description: "Emits `note` as a `Note` event in the query explanation. Query explanations show the exact expressions evaluated by OPA during policy execution. For example, `trace(\"Hello There!\")` includes `Note \"Hello There!\"` in the query explanation. To include variables in the message, use `sprintf`. For example, `person := \"Bob\"; trace(sprintf(\"Hello There! %v\", [person]))` will emit `Note \"Hello There! Bob\"` inside of the explanation.", 2586 Decl: types.NewFunction( 2587 types.Args( 2588 types.Named("note", types.S).Description("the note to include"), 2589 ), 2590 types.Named("result", types.B).Description("always `true`"), 2591 ), 2592 Categories: tracing, 2593 } 2594 2595 /** 2596 * Glob 2597 */ 2598 2599 var GlobMatch = &Builtin{ 2600 Name: "glob.match", 2601 Description: "Parses and matches strings against the glob notation. Not to be confused with `regex.globs_match`.", 2602 Decl: types.NewFunction( 2603 types.Args( 2604 types.Named("pattern", types.S), 2605 types.Named("delimiters", types.NewArray(nil, types.S)).Description("glob pattern delimiters, e.g. `[\".\", \":\"]`, defaults to `[\".\"]` if unset."), 2606 types.Named("match", types.S), 2607 ), 2608 types.Named("result", types.B).Description("true if `match` can be found in `pattern` which is separated by `delimiters`"), 2609 ), 2610 } 2611 2612 // GlobQuoteMeta 2613 var GlobQuoteMeta = &Builtin{ 2614 Name: "glob.quote_meta", 2615 Description: "Returns a string which represents a version of the pattern where all asterisks have been escaped.", 2616 Decl: types.NewFunction( 2617 types.Args( 2618 types.Named("pattern", types.S), 2619 ), 2620 types.Named("output", types.S).Description("the escaped string of `pattern`"), 2621 ), 2622 // TODO(sr): example for this was: Calling ``glob.quote_meta("*.github.com", output)`` returns ``\\*.github.com`` as ``output``. 2623 } 2624 2625 /** 2626 * Networking 2627 */ 2628 2629 var NetCIDRIntersects = &Builtin{ 2630 Name: "net.cidr_intersects", 2631 Description: "Checks if a CIDR intersects with another CIDR (e.g. `192.168.0.0/16` overlaps with `192.168.1.0/24`). Supports both IPv4 and IPv6 notations.", 2632 Decl: types.NewFunction( 2633 types.Args( 2634 types.Named("cidr1", types.S), 2635 types.Named("cidr2", types.S), 2636 ), 2637 types.Named("result", types.B), 2638 ), 2639 } 2640 2641 var NetCIDRExpand = &Builtin{ 2642 Name: "net.cidr_expand", 2643 Description: "Expands CIDR to set of hosts (e.g., `net.cidr_expand(\"192.168.0.0/30\")` generates 4 hosts: `{\"192.168.0.0\", \"192.168.0.1\", \"192.168.0.2\", \"192.168.0.3\"}`).", 2644 Decl: types.NewFunction( 2645 types.Args( 2646 types.Named("cidr", types.S), 2647 ), 2648 types.Named("hosts", types.NewSet(types.S)).Description("set of IP addresses the CIDR `cidr` expands to"), 2649 ), 2650 } 2651 2652 var NetCIDRContains = &Builtin{ 2653 Name: "net.cidr_contains", 2654 Description: "Checks if a CIDR or IP is contained within another CIDR. `output` is `true` if `cidr_or_ip` (e.g. `127.0.0.64/26` or `127.0.0.1`) is contained within `cidr` (e.g. `127.0.0.1/24`) and `false` otherwise. Supports both IPv4 and IPv6 notations.", 2655 Decl: types.NewFunction( 2656 types.Args( 2657 types.Named("cidr", types.S), 2658 types.Named("cidr_or_ip", types.S), 2659 ), 2660 types.Named("result", types.B), 2661 ), 2662 } 2663 2664 var NetCIDRContainsMatches = &Builtin{ 2665 Name: "net.cidr_contains_matches", 2666 Description: "Checks if collections of cidrs or ips are contained within another collection of cidrs and returns matches. " + 2667 "This function is similar to `net.cidr_contains` except it allows callers to pass collections of CIDRs or IPs as arguments and returns the matches (as opposed to a boolean result indicating a match between two CIDRs/IPs).", 2668 Decl: types.NewFunction( 2669 types.Args( 2670 types.Named("cidrs", netCidrContainsMatchesOperandType), 2671 types.Named("cidrs_or_ips", netCidrContainsMatchesOperandType), 2672 ), 2673 types.Named("output", types.NewSet(types.NewArray([]types.Type{types.A, types.A}, nil))).Description("tuples identifying matches where `cidrs_or_ips` are contained within `cidrs`"), 2674 ), 2675 } 2676 2677 var NetCIDRMerge = &Builtin{ 2678 Name: "net.cidr_merge", 2679 Description: "Merges IP addresses and subnets into the smallest possible list of CIDRs (e.g., `net.cidr_merge([\"192.0.128.0/24\", \"192.0.129.0/24\"])` generates `{\"192.0.128.0/23\"}`." + 2680 `This function merges adjacent subnets where possible, those contained within others and also removes any duplicates. 2681 Supports both IPv4 and IPv6 notations. IPv6 inputs need a prefix length (e.g. "/128").`, 2682 Decl: types.NewFunction( 2683 types.Args( 2684 types.Named("addrs", types.NewAny( 2685 types.NewArray(nil, types.NewAny(types.S)), 2686 types.NewSet(types.S), 2687 )).Description("CIDRs or IP addresses"), 2688 ), 2689 types.Named("output", types.NewSet(types.S)).Description("smallest possible set of CIDRs obtained after merging the provided list of IP addresses and subnets in `addrs`"), 2690 ), 2691 } 2692 2693 var netCidrContainsMatchesOperandType = types.NewAny( 2694 types.S, 2695 types.NewArray(nil, types.NewAny( 2696 types.S, 2697 types.NewArray(nil, types.A), 2698 )), 2699 types.NewSet(types.NewAny( 2700 types.S, 2701 types.NewArray(nil, types.A), 2702 )), 2703 types.NewObject(nil, types.NewDynamicProperty( 2704 types.S, 2705 types.NewAny( 2706 types.S, 2707 types.NewArray(nil, types.A), 2708 ), 2709 )), 2710 ) 2711 2712 var NetLookupIPAddr = &Builtin{ 2713 Name: "net.lookup_ip_addr", 2714 Description: "Returns the set of IP addresses (both v4 and v6) that the passed-in `name` resolves to using the standard name resolution mechanisms available.", 2715 Decl: types.NewFunction( 2716 types.Args( 2717 types.Named("name", types.S).Description("domain name to resolve"), 2718 ), 2719 types.Named("addrs", types.NewSet(types.S)).Description("IP addresses (v4 and v6) that `name` resolves to"), 2720 ), 2721 } 2722 2723 /** 2724 * Semantic Versions 2725 */ 2726 2727 var SemVerIsValid = &Builtin{ 2728 Name: "semver.is_valid", 2729 Description: "Validates that the input is a valid SemVer string.", 2730 Decl: types.NewFunction( 2731 types.Args( 2732 types.Named("vsn", types.A), 2733 ), 2734 types.Named("result", types.B).Description("`true` if `vsn` is a valid SemVer; `false` otherwise"), 2735 ), 2736 } 2737 2738 var SemVerCompare = &Builtin{ 2739 Name: "semver.compare", 2740 Description: "Compares valid SemVer formatted version strings.", 2741 Decl: types.NewFunction( 2742 types.Args( 2743 types.Named("a", types.S), 2744 types.Named("b", types.S), 2745 ), 2746 types.Named("result", types.N).Description("`-1` if `a < b`; `1` if `b > a`; `0` if `a == b`"), 2747 ), 2748 } 2749 2750 /** 2751 * Printing 2752 */ 2753 2754 // Print is a special built-in function that writes zero or more operands 2755 // to a message buffer. The caller controls how the buffer is displayed. The 2756 // operands may be of any type. Furthermore, unlike other built-in functions, 2757 // undefined operands DO NOT cause the print() function to fail during 2758 // evaluation. 2759 var Print = &Builtin{ 2760 Name: "print", 2761 Decl: types.NewVariadicFunction(nil, types.A, nil), 2762 } 2763 2764 // InternalPrint represents the internal implementation of the print() function. 2765 // The compiler rewrites print() calls to refer to the internal implementation. 2766 var InternalPrint = &Builtin{ 2767 Name: "internal.print", 2768 Decl: types.NewFunction([]types.Type{types.NewArray(nil, types.NewSet(types.A))}, nil), 2769 } 2770 2771 /** 2772 * Deprecated built-ins. 2773 */ 2774 2775 // SetDiff has been replaced by the minus built-in. 2776 var SetDiff = &Builtin{ 2777 Name: "set_diff", 2778 Decl: types.NewFunction( 2779 types.Args( 2780 types.NewSet(types.A), 2781 types.NewSet(types.A), 2782 ), 2783 types.NewSet(types.A), 2784 ), 2785 } 2786 2787 // NetCIDROverlap has been replaced by the `net.cidr_contains` built-in. 2788 var NetCIDROverlap = &Builtin{ 2789 Name: "net.cidr_overlap", 2790 Decl: types.NewFunction( 2791 types.Args( 2792 types.S, 2793 types.S, 2794 ), 2795 types.B, 2796 ), 2797 } 2798 2799 // CastArray checks the underlying type of the input. If it is array or set, an array 2800 // containing the values is returned. If it is not an array, an error is thrown. 2801 var CastArray = &Builtin{ 2802 Name: "cast_array", 2803 Decl: types.NewFunction( 2804 types.Args(types.A), 2805 types.NewArray(nil, types.A), 2806 ), 2807 } 2808 2809 // CastSet checks the underlying type of the input. 2810 // If it is a set, the set is returned. 2811 // If it is an array, the array is returned in set form (all duplicates removed) 2812 // If neither, an error is thrown 2813 var CastSet = &Builtin{ 2814 Name: "cast_set", 2815 Decl: types.NewFunction( 2816 types.Args(types.A), 2817 types.NewSet(types.A), 2818 ), 2819 } 2820 2821 // CastString returns input if it is a string; if not returns error. 2822 // For formatting variables, see sprintf 2823 var CastString = &Builtin{ 2824 Name: "cast_string", 2825 Decl: types.NewFunction( 2826 types.Args(types.A), 2827 types.S, 2828 ), 2829 } 2830 2831 // CastBoolean returns input if it is a boolean; if not returns error. 2832 var CastBoolean = &Builtin{ 2833 Name: "cast_boolean", 2834 Decl: types.NewFunction( 2835 types.Args(types.A), 2836 types.B, 2837 ), 2838 } 2839 2840 // CastNull returns null if input is null; if not returns error. 2841 var CastNull = &Builtin{ 2842 Name: "cast_null", 2843 Decl: types.NewFunction( 2844 types.Args(types.A), 2845 types.NewNull(), 2846 ), 2847 } 2848 2849 // CastObject returns the given object if it is null; throws an error otherwise 2850 var CastObject = &Builtin{ 2851 Name: "cast_object", 2852 Decl: types.NewFunction( 2853 types.Args(types.A), 2854 types.NewObject(nil, types.NewDynamicProperty(types.A, types.A)), 2855 ), 2856 } 2857 2858 // RegexMatchDeprecated declares `re_match` which has been deprecated. Use `regex.match` instead. 2859 var RegexMatchDeprecated = &Builtin{ 2860 Name: "re_match", 2861 Decl: types.NewFunction( 2862 types.Args( 2863 types.S, 2864 types.S, 2865 ), 2866 types.B, 2867 ), 2868 } 2869 2870 // All takes a list and returns true if all of the items 2871 // are true. A collection of length 0 returns true. 2872 var All = &Builtin{ 2873 Name: "all", 2874 Decl: types.NewFunction( 2875 types.Args( 2876 types.NewAny( 2877 types.NewSet(types.A), 2878 types.NewArray(nil, types.A), 2879 ), 2880 ), 2881 types.B, 2882 ), 2883 deprecated: true, 2884 } 2885 2886 // Any takes a collection and returns true if any of the items 2887 // is true. A collection of length 0 returns false. 2888 var Any = &Builtin{ 2889 Name: "any", 2890 Decl: types.NewFunction( 2891 types.Args( 2892 types.NewAny( 2893 types.NewSet(types.A), 2894 types.NewArray(nil, types.A), 2895 ), 2896 ), 2897 types.B, 2898 ), 2899 deprecated: true, 2900 } 2901 2902 // Builtin represents a built-in function supported by OPA. Every built-in 2903 // function is uniquely identified by a name. 2904 type Builtin struct { 2905 Name string `json:"name"` // Unique name of built-in function, e.g., <name>(arg1,arg2,...,argN) 2906 Description string `json:"description,omitempty"` // Description of what the built-in function does. 2907 2908 // Categories of the built-in function. Omitted for namespaced 2909 // built-ins, i.e. "array.concat" is taken to be of the "array" category. 2910 // "minus" for example, is part of two categories: numbers and sets. (NOTE(sr): aspirational) 2911 Categories []string `json:"categories,omitempty"` 2912 2913 Decl *types.Function `json:"decl"` // Built-in function type declaration. 2914 Infix string `json:"infix,omitempty"` // Unique name of infix operator. Default should be unset. 2915 Relation bool `json:"relation,omitempty"` // Indicates if the built-in acts as a relation. 2916 deprecated bool // Indicates if the built-in has been deprecated. 2917 } 2918 2919 // category is a helper for specifying a Builtin's Categories 2920 func category(cs ...string) []string { 2921 return cs 2922 } 2923 2924 // IsDeprecated returns true if the Builtin function is deprecated and will be removed in a future release. 2925 func (b *Builtin) IsDeprecated() bool { 2926 return b.deprecated 2927 } 2928 2929 // Expr creates a new expression for the built-in with the given operands. 2930 func (b *Builtin) Expr(operands ...*Term) *Expr { 2931 ts := make([]*Term, len(operands)+1) 2932 ts[0] = NewTerm(b.Ref()) 2933 for i := range operands { 2934 ts[i+1] = operands[i] 2935 } 2936 return &Expr{ 2937 Terms: ts, 2938 } 2939 } 2940 2941 // Call creates a new term for the built-in with the given operands. 2942 func (b *Builtin) Call(operands ...*Term) *Term { 2943 call := make(Call, len(operands)+1) 2944 call[0] = NewTerm(b.Ref()) 2945 for i := range operands { 2946 call[i+1] = operands[i] 2947 } 2948 return NewTerm(call) 2949 } 2950 2951 // Ref returns a Ref that refers to the built-in function. 2952 func (b *Builtin) Ref() Ref { 2953 parts := strings.Split(b.Name, ".") 2954 ref := make(Ref, len(parts)) 2955 ref[0] = VarTerm(parts[0]) 2956 for i := 1; i < len(parts); i++ { 2957 ref[i] = StringTerm(parts[i]) 2958 } 2959 return ref 2960 } 2961 2962 // IsTargetPos returns true if a variable in the i-th position will be bound by 2963 // evaluating the call expression. 2964 func (b *Builtin) IsTargetPos(i int) bool { 2965 return len(b.Decl.Args()) == i 2966 } 2967 2968 func init() { 2969 BuiltinMap = map[string]*Builtin{} 2970 for _, b := range DefaultBuiltins { 2971 RegisterBuiltin(b) 2972 } 2973 }