### Function Installation Example

Source: https://github.com/crossplane-contrib/function-sequencer/blob/main/_autodocs/api-reference/cli.md

YAML configuration for installing the function-sequencer as a Crossplane ClusterFunction, showing how Crossplane manages certificate mounting and environment variables.

```yaml
apiVersion: pkg.crossplane.io/v1
kind: Function
metadata:
  name: function-sequencer
spec:
  package: xpkg.crossplane.io/crossplane-contrib/function-sequencer:v0.5.0
```

--------------------------------

### Custom Network Configuration Example

Source: https://github.com/crossplane-contrib/function-sequencer/blob/main/_autodocs/api-reference/cli.md

Example demonstrating custom network configuration for the function-sequencer, allowing it to listen on a specific IP address and port.

```bash
# Listen on specific IP and port
./function-sequencer \
  --network tcp \
  --address "192.168.1.100:9443" \
  --tls-server-certs-dir /certs
```

--------------------------------

### Production with mTLS Example

Source: https://github.com/crossplane-contrib/function-sequencer/blob/main/_autodocs/api-reference/cli.md

Example of running the function-sequencer in production with TLS certificates and default settings. Requires specifying the TLS certificate directory and address.

```bash
# Run with TLS certificates and default settings
./function-sequencer \
  --tls-server-certs-dir /etc/crossplane/function-certs \
  --address :9443
```

--------------------------------

### Large Composition Support Example

Source: https://github.com/crossplane-contrib/function-sequencer/blob/main/_autodocs/api-reference/cli.md

Example for configuring the function-sequencer to support very large compositions by increasing the maximum received message size.

```bash
# Increase message size for very large compositions
./function-sequencer \
  --max-recv-message-size 16 \
  --tls-server-certs-dir /certs
```

--------------------------------

### Sequencing Rule Configuration Example

Source: https://github.com/crossplane-contrib/function-sequencer/blob/main/_autodocs/configuration.md

Illustrates the configuration of a single sequencing rule within the rules array. This example shows a sequence of resources, an optional condition, and the deleteOnly flag.

```yaml
rules:
  - sequence:
      - resource-a
      - resource-b
      - resource-c
    condition: "optional.cel.expression == true"
    deleteOnly: false
```

--------------------------------

### Development with Debug Logging Example

Source: https://github.com/crossplane-contrib/function-sequencer/blob/main/_autodocs/api-reference/cli.md

Example of running the function-sequencer with insecure transport and debug logs enabled. Useful for local testing and debugging sequencing logic.

```bash
# Run with insecure transport and debug logs
go run . --insecure --debug
```

--------------------------------

### Unix Socket Configuration Example

Source: https://github.com/crossplane-contrib/function-sequencer/blob/main/_autodocs/api-reference/cli.md

Example showing how to configure the function-sequencer to use a Unix socket instead of TCP for communication. This is an uncommon configuration.

```bash
# Use Unix socket instead of TCP
./function-sequencer \
  --network unix \
  --address /var/run/function-sequencer.sock \
  --tls-server-certs-dir /certs
```

--------------------------------

### Input Configuration Example

Source: https://github.com/crossplane-contrib/function-sequencer/blob/main/_autodocs/api-reference/input.md

Example of the Input configuration structure used for the function-sequencer. This YAML demonstrates how to set caching TTL, enable deletion sequencing and replay, specify usage version, reset composite readiness, and define sequencing rules with conditions.

```yaml
apiVersion: sequencer.fn.crossplane.io/v1beta1
kind: Input
cacheTTL: "5m"
enableDeletionSequencing: true
replayDeletion: true
usageVersion: "v2"
resetCompositeReadiness: true
rules:
  - sequence:
      - vpc
      - subnet
      - instance
  - sequence:
      - subnet
      - security-group
    condition: "observed.composite.resource.spec.securityEnabled == true"
```

--------------------------------

### Environment Variable Usage Example

Source: https://github.com/crossplane-contrib/function-sequencer/blob/main/_autodocs/api-reference/cli.md

Example demonstrating how to set the TLS_SERVER_CERTS_DIR environment variable to configure the function-sequencer's TLS settings.

```bash
export TLS_SERVER_CERTS_DIR=/etc/crossplane/function-certs
./function-sequencer
```

--------------------------------

### Regex Pattern Example for Rendering

Source: https://github.com/crossplane-contrib/function-sequencer/blob/main/example/README.md

Use `crossplane render` with a composition that includes regex patterns to define resource configurations. This example demonstrates rendering an XR with specific resource definitions and observing the resulting status.

```shell
$ crossplane render xr.yaml composition-regex.yaml functions.yaml -r -o observed-regex.yaml
```

```yaml
---
apiversion: example.crossplane.io/v1
kind: XR
metadata:
  name: example-xr
status:
  conditions:
  - lastTransitionTime: "2024-01-01T00:00:00Z"
    message: 'Unready resources: second-object'
    reason: Creating
    status: "False"
    type: Ready
---
apiversion: nop.crossplane.io/v1alpha1
kind: NopResource
metadata:
  annotations:
    crossplane.io/composition-resource-name: first-subresource-1
  labels:
    crossplane.io/composite: example-xr
  name: first-subresource-1
  ownerReferences:
  - apiversion: example.crossplane.io/v1
    blockOwnerDeletion: true
    controller: true
    kind: XR
    name: example-xr
    uid: ""
spec:
  forProvider:
    conditionAfter:
    - conditionStatus: "False"
      conditionType: Ready
      time: 5s
    - conditionStatus: "True"
      conditionType: Ready
      time: 10s
    - conditionStatus: "False"
      conditionType: Ready
      time: 30s
    - conditionStatus: "True"
      conditionType: Ready
      time: 90s
---
apiversion: nop.crossplane.io/v1alpha1
kind: NopResource
metadata:
  annotations:
    crossplane.io/composition-resource-name: first-subresource-2
  labels:
    crossplane.io/composite: example-xr
  name: first-subresource-2
  ownerReferences:
  - apiversion: example.crossplane.io/v1
    blockOwnerDeletion: true
    controller: true
    kind: XR
    name: example-xr
    uid: ""
spec:
  forProvider:
    conditionAfter:
    - conditionStatus: "False"
      conditionType: Ready
      time: 5s
    - conditionStatus: "True"
      conditionType: Ready
      time: 10s
---
apiversion: nop.crossplane.io/v1alpha1
kind: NopResource
metadata:
  annotations:
    crossplane.io/composition-resource-name: second-object
  labels:
    crossplane.io/composite: example-xr
  name: second-object
  ownerReferences:
  - apiversion: example.crossplane.io/v1
    blockOwnerDeletion: true
    controller: true
    kind: XR
    name: example-xr
    uid: ""
spec:
  forProvider:
    conditionAfter:
    - conditionStatus: "False"
      conditionType: Ready
      time: 5s
    - conditionStatus: "True"
      conditionType: Ready
      time: 10s
---
apiversion: render.crossplane.io/v1beta1
kind: Result
message: Delaying creation of resource(s) matching "third-resource" because "object$"
is not fully ready (0 of 1)
severity: SEVERITY_NORMAL
step: sequence-creation
```

--------------------------------

### Basic Composition with Sequenced Resources

Source: https://github.com/crossplane-contrib/function-sequencer/blob/main/_autodocs/usage-patterns.md

This example demonstrates a basic composition using the Function Sequencer to manage the creation order of two sequenced resources within a pipeline.

```yaml
apiVersion: apiextensions.crossplane.io/v1
kind: Composition
metadata:
  name: basic-sequence
spec:
  compositeTypeRef:
    apiVersion: example.crossplane.io/v1
    kind: XR
  mode: Pipeline
  pipeline:
    - step: create-resources
      functionRef:
        name: function-patch-and-transform
      input:
        # ... resource definitions ...
    
    - step: sequence
      functionRef:
        name: function-sequencer
      input:
        apiVersion: sequencer.fn.crossplane.io/v1beta1
        kind: Input
        rules:
          - sequence:
              - network
              - compute
```

--------------------------------

### UsageVersion YAML Input Example

Source: https://github.com/crossplane-contrib/function-sequencer/blob/main/_autodocs/api-reference/input.md

Example of how to specify the usageVersion in YAML composition input. Choose v1 for older, cluster-scoped Crossplane resources, and v2 for modern Crossplane with protection APIs supporting both cluster-scoped and namespaced resources.

```yaml
// In YAML composition input
usageVersion: "v2"
```

```text
// Choose based on Crossplane version and resource types
// v1: cluster-scoped only, older Crossplane
// v2: both cluster and namespaced, modern Crossplane with protection APIs
```

--------------------------------

### SequencingRule YAML Examples

Source: https://github.com/crossplane-contrib/function-sequencer/blob/main/_autodocs/api-reference/input.md

Illustrates various ways to define sequencing rules in YAML, including basic sequential creation, regex-based matching, conditional sequencing, and delete-only rules.

```yaml
rules:
  # Basic sequential creation: network → compute → storage
  - sequence:
      - network
      - compute
      - storage
  
  # Regex-based matching with groups
  - sequence:
      - primary-resource
      - dependent-.*
  
  # Conditional sequencing
  - sequence:
      - vpc
      - nat-gateway
    condition: "observed.composite.resource.spec.enableNat == true"
  
  # Delete-only (eventual consistency for creation)
  - sequence:
      - base
      - dependent
    deleteOnly: true
```

--------------------------------

### GenerateName for Usage Resources

Source: https://github.com/crossplane-contrib/function-sequencer/blob/main/_autodocs/api-reference/name-generation.md

Shows an example of using GenerateName internally for creating unique names for Usage resources, ensuring each resource has a distinct and valid identifier.

```go
// Used internally for Usage resources
// When generating: "by=subnet, of=vpc"
usageName := GenerateName("vpc-subnet-usage", "dependency")
// This ensures each generated Usage has a unique, valid name
```

--------------------------------

### Call Function with Example Manifests

Source: https://github.com/crossplane-contrib/function-sequencer/blob/main/example/README.md

Render an XR, composition, and function manifest to test the function's output. This manifest defines an XR and a Result indicating it was processed.

```shell
$ crossplane render xr.yaml composition.yaml functions.yaml -r
```

```yaml
---
apiversion: example.crossplane.io/v1
kind: XR
metadata:
  name: example-xr
---
apiversion: render.crossplane.io/v1beta1
kind: Result
message: I was run with input "Hello world"!
severity: SEVERITY_NORMAL
step: run-the-template
```

--------------------------------

### Sequence Resource Creation

Source: https://github.com/crossplane-contrib/function-sequencer/blob/main/README.md

Ensures that 'second-resource' and 'third-resource' are not created until 'first-resource' is ready. This is a basic example of explicit resource sequencing.

```yaml
  - step: sequence-creation
    functionRef:
      name: function-sequencer
    input:
      apiVersion: sequencer.fn.crossplane.io/v1beta1
      kind: Input
      rules:
        - sequence:
          - first-resource
          - second-resource
        - sequence:
          - first-resource
          - third-resource
```

--------------------------------

### Example Valid Regex Pattern

Source: https://github.com/crossplane-contrib/function-sequencer/blob/main/_autodocs/errors.md

Illustrates valid regular expression patterns that can be used for resource names. Supports wildcards, anchors, and OR operators.

```regex
"vpc-.*"
"^vpc"
"subnet$"
"^(prod|staging)-.*$"
```

--------------------------------

### Run Method Signature

Source: https://github.com/crossplane-contrib/function-sequencer/blob/main/_autodocs/api-reference/cli.md

Signature for the Run method of the CLI struct, which starts the function-sequencer as a gRPC server.

```go
func (c *CLI) Run() error
```

--------------------------------

### XR Manifest for Deletion Sequencing

Source: https://github.com/crossplane-contrib/function-sequencer/blob/main/example/README.md

This YAML defines an example XR with multiple NopResource claims and Usage resources. The Usage resources specify dependencies and `replayDeletion: true`, which dictates the order in which resources are deleted.

```yaml
---
aspiVersion: example.crossplane.io/v1
kind: XR
metadata:
  name: example-xr
status:
  conditions:
  - lastTransitionTime: "2024-01-01T00:00:00Z"
    reason: Available
    status: "True"
    type: Ready
---
aspiVersion: nop.crossplane.io/v1alpha1
kind: NopResource
metadata:
  annotations:
    crossplane.io/composition-resource-name: first-resource
  labels:
    crossplane.io/composite: example-xr
  name: first
  ownerReferences:
  - apiVersion: example.crossplane.io/v1
    blockOwnerDeletion: true
    controller: true
    kind: XR
    name: example-xr
    uid: ""
spec:
  forProvider:
    conditionAfter:
    - conditionStatus: "False"
      conditionType: Ready
      time: 5s
    - conditionStatus: "True"
      conditionType: Ready
      time: 10s
    - conditionStatus: "False"
      conditionType: Ready
      time: 30s
    - conditionStatus: "True"
      conditionType: Ready
      time: 90s
---
aspiVersion: nop.crossplane.io/v1alpha1
kind: NopResource
metadata:
  annotations:
    crossplane.io/composition-resource-name: second-resource
  labels:
    crossplane.io/composite: example-xr
  name: second
  ownerReferences:
  - apiVersion: example.crossplane.io/v1
    blockOwnerDeletion: true
    controller: true
    kind: XR
    name: example-xr
    uid: ""
spec:
  forProvider:
    conditionAfter:
    - conditionStatus: "False"
      conditionType: Ready
      time: 5s
    - conditionStatus: "True"
      conditionType: Ready
      time: 10s
---
aspiVersion: apiextensions.crossplane.io/v1beta1
kind: Usage
metadata:
  annotations:
    crossplane.io/composition-resource-name: second-resource-first-resource-usage
  labels:
    crossplane.io/composite: example-xr
  name: nopresource-second-nopresource-first-4f1a57-dependency
  ownerReferences:
  - apiVersion: example.crossplane.io/v1
    blockOwnerDeletion: true
    controller: true
    kind: XR
    name: example-xr
    uid: ""
spec:
  by:
    apiVersion: nop.crossplane.io/v1alpha1
    kind: NopResource
    resourceRef:
      name: second
  of:
    apiVersion: nop.crossplane.io/v1alpha1
    kind: NopResource
    resourceRef:
      name: first
  reason: dependency
  replayDeletion: true
---
aspiVersion: nop.crossplane.io/v1alpha1
kind: NopResource
metadata:
  annotations:
    crossplane.io/composition-resource-name: third-resource
  labels:
    crossplane.io/composite: example-xr
  name: third
  ownerReferences:
  - apiVersion: example.crossplane.io/v1
    blockOwnerDeletion: true
    controller: true
    kind: XR
    name: example-xr
    uid: ""
spec:
  forProvider:
    conditionAfter:
    - conditionStatus: "False"
      conditionType: Ready
      time: 5s
    - conditionStatus: "True"
      conditionType: Ready
      time: 10s
---
aspiVersion: apiextensions.crossplane.io/v1beta1
kind: Usage
metadata:
  annotations:
    crossplane.io/composition-resource-name: third-resource-first-resource-usage
  labels:
    crossplane.io/composite: example-xr
  name: nopresource-third-nopresource-first-1b4fc5-dependency
  ownerReferences:
  - apiVersion: example.crossplane.io/v1
    blockOwnerDeletion: true
    controller: true
    kind: XR
    name: example-xr
    uid: ""
spec:
  by:
    apiVersion: nop.crossplane.io/v1alpha1
    kind: NopResource
    resourceRef:
      name: third
  of:
    apiVersion: nop.crossplane.io/v1alpha1
    kind: NopResource
    resourceRef:
      name: first
  reason: dependency
  replayDeletion: true

```

--------------------------------

### Example Invalid Regex Pattern

Source: https://github.com/crossplane-contrib/function-sequencer/blob/main/_autodocs/errors.md

Shows examples of invalid regular expression patterns that would cause a regex compilation error. Ensure correct regex syntax for resource names.

```regex
"(unclosed"
"[a-"
"(?P<invalid"
```

--------------------------------

### Function Invocation Example

Source: https://github.com/crossplane-contrib/function-sequencer/blob/main/_autodocs/api-reference/function.md

Example of how the function-sequencer is invoked within a Crossplane Composition pipeline. It specifies the function, input configuration including cache TTL, deletion sequencing, and sequencing rules.

```yaml
apiVersion: apiextensions.crossplane.io/v1
kind: Composition
metadata:
  name: example-composition
spec:
  compositeTypeRef:
    apiVersion: example.crossplane.io/v1
    kind: ExampleXR
  mode: Pipeline
  pipeline:
    - step: sequencing
      functionRef:
        name: function-sequencer
      input:
        apiVersion: sequencer.fn.crossplane.io/v1beta1
        kind: Input
        cacheTTL: "5m"
        enableDeletionSequencing: true
        rules:
          - sequence:
              - first-resource
              - second-resource
```

--------------------------------

### Regex Matching Behavior

Source: https://github.com/crossplane-contrib/function-sequencer/blob/main/README.md

Illustrates the default strict matching behavior of regex in resource sequencing rules. It shows how explicit start ('^') and end ('$') anchors affect matching.

```yaml
yaml
- resource    # this has no explicit start or end, so it will match EXACTLY ^resource$ (normal behaviour)
- a-group-.*  # this has no explicit start or end, so it will match EXACTLY ^a-group-.*$
- ^a-group    # this has an explicit start, so it will match EVERYTHING that starts with a-group
- a-group$    # this has an explicit end, so it will match EVERYTHING that ends with a-group
```

--------------------------------

### Example Invalid Function Input

Source: https://github.com/crossplane-contrib/function-sequencer/blob/main/_autodocs/errors.md

Illustrates malformed or missing input for a Composition function step. Ensure the input object has the correct apiVersion and kind.

```yaml
- step: sequence
  functionRef:
    name: function-sequencer
  input: null # Missing
  # OR
  input:
    apiVersion: wrong/v1
    kind: WrongType
```

--------------------------------

### Function Sequencer CLI Default Execution

Source: https://github.com/crossplane-contrib/function-sequencer/blob/main/_autodocs/api-reference/cli.md

Runs the function-sequencer CLI with default settings. This starts the server with TCP networking, listening on all IPv4 interfaces on port 9443, requiring TLS, and disabling debug logging.

```bash
./function-sequencer
```

--------------------------------

### Basic Sequencing Configuration

Source: https://github.com/crossplane-contrib/function-sequencer/blob/main/_autodocs/configuration.md

Defines a basic sequence for resource creation: VPC, then subnet, then instance. Subnet creation waits for VPC readiness, and instance creation waits for subnet readiness.

```yaml
- step: sequence-creation
  functionRef:
    name: function-sequencer
  input:
    apiVersion: sequencer.fn.crossplane.io/v1beta1
    kind: Input
    rules:
      - sequence:
          - vpc
          - subnet
          - instance
```

--------------------------------

### V1 vs V2 Usage Selection Logic

Source: https://github.com/crossplane-contrib/function-sequencer/blob/main/_autodocs/architecture.md

Illustrates the conditional logic for selecting between V1 and V2 Usage generation based on a usage version flag.

```go
if usageVersion == UsageV1:
    return GenerateV1Usage(of, by, replayDeletion)
else:
    return GenerateV2Usage(of, by, replayDeletion)
```

--------------------------------

### Creation Sequencing Algorithm Logic

Source: https://github.com/crossplane-contrib/function-sequencer/blob/main/_autodocs/architecture.md

Illustrates the logic for the creation sequencing algorithm, checking dependencies between resources in a sequence (e.g., A, B, C). It determines if dependent resources should be removed from the desired state if predecessors are not ready.

```go
i = 1: Check B depends on A
  ├─ If A not in desired: Remove B from desired, mark composite not-ready
  ├─ If A in desired:
  │  ├─ Count: desired A's that are ready
  │  └─ If not all A's ready: Remove B from desired, mark composite not-ready

i = 2: Check C depends on both A and B
  ├─ For each predecessor (A, B):
  │  ├─ If predecessor not all ready: Remove C from desired, break
```

--------------------------------

### Full Function Sequencer Input Configuration with Defaults

Source: https://github.com/crossplane-contrib/function-sequencer/blob/main/_autodocs/configuration.md

Illustrates a comprehensive configuration for the Function Sequencer, including all available options and their default values.

```yaml
apiVersion: sequencer.fn.crossplane.io/v1beta1
kind: Input
cacheTTL: "1m"
enableDeletionSequencing: false
replayDeletion: true
usageVersion: "v2"
resetCompositeReadiness: false
rules:
  - sequence:
      - a
      - b
    deleteOnly: false
    # condition: "" (no condition)
```

--------------------------------

### Sequence Resource Creation with Regex

Source: https://github.com/crossplane-contrib/function-sequencer/blob/main/README.md

Ensures that 'second-resource' is not created until all resources matching the regex 'first-subresource-.*' are ready. This demonstrates using regex for flexible resource grouping.

```yaml
  - step: sequence-creation
    functionRef:
      name: function-sequencer
    input:
      apiVersion: sequencer.fn.crossplane.io/v1beta1
      kind: Input
      rules:
        - sequence:
          - first-subresource-.*
          - second-resource
```

--------------------------------

### Compile Regex with Auto-Anchoring

Source: https://github.com/crossplane-contrib/function-sequencer/blob/main/_autodocs/architecture.md

Compiles a regex pattern, automatically adding start ('^') and end ('$') anchors if they are not explicitly provided. This enforces exact matching by default.

```go
func getStrictRegex(pattern string) (*regexp.Regexp, error) {
    if !strings.HasPrefix(pattern, "^") && !strings.HasSuffix(pattern, "$") {
        // No explicit anchors → add both
        pattern = fmt.Sprintf("^%s$", pattern)
    }
    return regexp.Compile(pattern)
}
```

--------------------------------

### Basic GenerateName Usage

Source: https://github.com/crossplane-contrib/function-sequencer/blob/main/_autodocs/api-reference/name-generation.md

Demonstrates the basic usage of the GenerateName function with a typical resource name and suffix. The output is a compliant Kubernetes name, potentially truncated if the combined length exceeds limits.

```go
import "github.com/crossplane/function-sequencer"

// Basic usage
name := GenerateName("vpc-subnet-instance", "dependency")
// Output: "vpc-subnet-instance-a1b2c3-dependency" (if under 63 chars)
```

--------------------------------

### Run Basic Sequencing Test

Source: https://github.com/crossplane-contrib/function-sequencer/blob/main/_autodocs/architecture.md

Execute a basic sequencing test using `crossplane render` with XR, Composition, and Functions definitions.

```bash
crossplane render example/xr.yaml example/composition.yaml \
  example/functions.yaml
```

--------------------------------

### Terraform Integration for Infrastructure as Code

Source: https://github.com/crossplane-contrib/function-sequencer/blob/main/_autodocs/usage-patterns.md

Example of using the function-sequencer within a Crossplane composition when integrating with the Terraform provider. This defines a sequencing step with specific rules for resource provisioning.

```hcl
resource "crossplane_composition" "vpc_to_compute" {
  name = "vpc-to-compute"
  
  pipeline {
    step {
      name      = "patch-and-transform"
      ref_name  = "function-patch-and-transform"
      # ...
    }
    
    step {
      name      = "sequencing"
      ref_name  = "function-sequencer"
      input = {
        apiVersion = "sequencer.fn.crossplane.io/v1beta1"
        kind       = "Input"
        rules = [
          {
            sequence = ["vpc", "subnet", "instance"]
          }
        ]
      }
    }
  }
}
```

--------------------------------

### Example Invalid Cache TTL Format

Source: https://github.com/crossplane-contrib/function-sequencer/blob/main/_autodocs/errors.md

Demonstrates an invalid duration string for the cacheTTL field. Use valid Go duration formats like '1m', '30s', or '2h'.

```yaml
cacheTTL: invalid
```

--------------------------------

### Regex Matching Sequencing with crossplane render

Source: https://github.com/crossplane-contrib/function-sequencer/blob/main/_autodocs/README.md

This command demonstrates sequencing using regex matching for resource selection.

```bash
crossplane render example/xr.yaml example/composition-regex.yaml example/functions.yaml
```

--------------------------------

### Render XR with Deletion Sequencing

Source: https://github.com/crossplane-contrib/function-sequencer/blob/main/example/README.md

This command renders an XR manifest along with composition and function definitions to observe deletion sequencing. The output file `observed-deletion-sequencing.yaml` will contain the rendered resources, including Usage objects that define deletion dependencies.

```shell
$ crossplane render xr.yaml composition-with-deletion-sequencing.yaml functions.yaml -r -o observed-deletion-sequencing.yaml
```

--------------------------------

### Main Entry Point for Function Sequencer CLI

Source: https://github.com/crossplane-contrib/function-sequencer/blob/main/_autodocs/api-reference/cli.md

The main function parses command-line arguments using the kong library and executes the CLI's run method. It ensures the program exits with a non-zero status code if any error occurs during execution.

```go
func main() {
    ctx := kong.Parse(&CLI{}, kong.Description("A Crossplane Composition Function."))
    ctx.FatalIfErrorf(ctx.Run())
}
```

--------------------------------

### Kubernetes CRD with Crossplane Composition

Source: https://github.com/crossplane-contrib/function-sequencer/blob/main/_autodocs/usage-patterns.md

Integrate the function-sequencer as part of a larger Crossplane CRD composition. This example shows a `Platform` CRD that implicitly sequences networking, compute, storage, and application resources.

```yaml
apiVersion: example.crossplane.io/v1
kind: Platform
metadata:
  name: my-platform
spec:
  networking:
    enabled: true
    vpcCIDR: 10.0.0.0/16
  compute:
    enabled: true
    replicas: 3
  storage:
    enabled: true
    size: 100Gi

# Composition automatically sequences:
# 1. Network resources (VPC, subnets, routes)
# 2. Compute resources (clusters, node pools)
# 3. Storage resources (disks, databases)
# 4. Applications (controllers, operators)
```

--------------------------------

### Parallel Chains with Common Root

Source: https://github.com/crossplane-contrib/function-sequencer/blob/main/_autodocs/usage-patterns.md

Illustrates how to create multiple resources in parallel after a common root resource is ready. Supports parallel deletion of dependent resources before the root.

```yaml
rules:
  - sequence:
      - vpc
      - subnet-a
  - sequence:
      - vpc
      - subnet-b
  - sequence:
      - vpc
      - security-group
```

--------------------------------

### Run Function Sequencer Locally

Source: https://github.com/crossplane-contrib/function-sequencer/blob/main/README.md

Use `go run` to execute the function-sequencer locally for development. The `--insecure` and `--debug` flags can be used for testing.

```sh
go run . --insecure --debug
```

--------------------------------

### Run Function Sequencer as CLI Tool

Source: https://github.com/crossplane-contrib/function-sequencer/blob/main/_autodocs/README.md

Execute the function sequencer as a command-line tool. Use flags to configure logging, network settings, address, TLS, and message size.

```bash
go run . [flags]
```

--------------------------------

### CLI.Run

Source: https://github.com/crossplane-contrib/function-sequencer/blob/main/_autodocs/SUMMARY.txt

Runs the command-line interface, processing commands and options.

```APIDOC
## CLI.Run

### Description
Executes the command-line interface, handling user commands and configuration options.

### Method
CLI.Run

### Parameters
- **command-line options**: Various flags and arguments to configure the CLI behavior.
```

--------------------------------

### CLI Configuration Structure

Source: https://github.com/crossplane-contrib/function-sequencer/blob/main/_autodocs/api-reference/cli.md

Defines the configuration structure for command-line arguments and server options for the function-sequencer CLI.

```go
type CLI struct {
    Debug              bool
    Network            string
    Address            string
    TLSCertsDir        string
    Insecure           bool
    MaxRecvMessageSize int
}
```

--------------------------------

### Lazy Initialization of CEL Environment

Source: https://github.com/crossplane-contrib/function-sequencer/blob/main/_autodocs/architecture.md

Ensures the CEL environment is initialized only once on its first use, providing zero overhead for compositions without conditions and maintaining thread safety.

```go
var getCELEnv = sync.OnceValues(func() (*cel.Env, error) { ... })
```

--------------------------------

### Responsive Composite Status with Pending Dependencies

Source: https://github.com/crossplane-contrib/function-sequencer/blob/main/_autodocs/usage-patterns.md

Configure the sequencer to reset composite readiness when pending dependencies exist. This prevents controllers from acting on incomplete compositions and indicates to users that resources are still being set up.

```yaml
rules:
  - sequence:
      - network
      - compute
resetCompositeReadiness: true
```

--------------------------------

### Creation Sequencing Rule

Source: https://github.com/crossplane-contrib/function-sequencer/blob/main/_autodocs/README.md

Defines the order in which resources should be created. Each resource in the sequence waits for its predecessors to be ready.

```yaml
rules:
  - sequence: [vpc, subnet, instance]
```

--------------------------------

### Handle Flaky Resources with Conditions and Cache TTL

Source: https://github.com/crossplane-contrib/function-sequencer/blob/main/_autodocs/usage-patterns.md

Manage resources with variable readiness times by using conditions to check their status and a short `cacheTTL` to quickly detect readiness changes. This ensures dependent services are only reconciled when the external API is truly ready, and allows for safe deletion if the external API becomes unready.

```yaml
rules:
  - sequence:
      - external-api
      - dependent-service
    condition: "observed.resources['external-api'].resource.status.ready == true"
  
cacheTTL: "30s"  # Short cache for flaky resources
```

--------------------------------

### Test Sequencing Locally with `crossplane render`

Source: https://github.com/crossplane-contrib/function-sequencer/blob/main/_autodocs/usage-patterns.md

Use `crossplane render` to validate sequencing logic locally. This command simulates the rendering process, showing which resources are in a desired state, which were removed due to sequencing, and provides status messages. It can also test with observed resources to simulate pre-existing infrastructure.

```bash
# Setup
cp example/composition.yaml my-composition.yaml
cp example/xr.yaml my-xr.yaml
cp example/functions.yaml my-functions.yaml

# Test creation sequencing
crossplane render my-xr.yaml my-composition.yaml my-functions.yaml

# Test with observed resources (simulating already-created resources)
crossplane render my-xr.yaml my-composition.yaml my-functions.yaml \
  --observed-resources example/observed.yaml

# Output shows:
# - Which resources are in desired state
# - Which were removed due to sequencing
# - Normal status messages explaining delays
```

--------------------------------

### Testing Composition with `crossplane render`

Source: https://github.com/crossplane-contrib/function-sequencer/blob/main/_autodocs/errors.md

Use this command to test your composition with function input before deploying to a cluster. It validates input parsing, function execution, and error messages.

```bash
crossplane render example/xr.yaml example/composition.yaml example/functions.yaml
```

--------------------------------

### Regex Matching for Sequencing

Source: https://github.com/crossplane-contrib/function-sequencer/blob/main/_autodocs/configuration.md

Uses regex to define sequences. All resources matching `network-*` must be ready before `compute-instance` is created.

```yaml
- step: sequence-regex
  functionRef:
    name: function-sequencer
  input:
    apiVersion: sequencer.fn.crossplane.io/v1beta1
    kind: Input
    rules:
      - sequence:
          - network-.*
          - compute-instance
```

--------------------------------

### GenerateName Usage with Truncation

Source: https://github.com/crossplane-contrib/function-sequencer/blob/main/_autodocs/api-reference/name-generation.md

Illustrates how GenerateName handles excessively long base names by truncating them to ensure the final name adheres to the 63-character limit while still including the hash and suffix.

```go
// Long name requiring truncation
name := GenerateName(
    "very-long-resource-name-that-exceeds-kubernetes-limits-significantly",
    "dependency",
)
// Output: "very-long-resource-name-that-exceed-a1b2c3-dependency" (exactly 63 chars)
```

--------------------------------

### RunFunction

Source: https://github.com/crossplane-contrib/function-sequencer/blob/main/_autodocs/SUMMARY.txt

Executes the sequencing logic. It takes a context and a request object, returning a response and an error.

```APIDOC
## RunFunction

### Description
Executes the sequencing logic based on the provided input.

### Method
Function.RunFunction

### Signature
RunFunction(ctx, req) (*Response, error)

### Parameters
- **ctx**: Context for the operation.
- **req**: The request object containing input for the function.

### Returns
- **Response**: The result of the function execution.
- **error**: An error if the function execution fails.
```

--------------------------------

### Mixed Sequencing Rules

Source: https://github.com/crossplane-contrib/function-sequencer/blob/main/README.md

Demonstrates mixing creation-sequenced and delete-only rules within the same composition. Allows different ordering strategies for different resource groups.

```yaml
rules:
  - sequence:
    - vpc
    - subnet
  - sequence:
    - subnet
    - security-group
    deleteOnly: true
```

--------------------------------

### Enable Deletion Sequencing with Regular Expressions

Source: https://github.com/crossplane-contrib/function-sequencer/blob/main/README.md

This snippet demonstrates enabling deletion sequencing using regular expressions for resource matching. It defines dependencies where resources matching `first-subresource-.*` are deleted after `second-resource`. This ensures a specific resource is deleted before a set of pattern-matched resources.

```yaml
  - step: sequence-creation-and-deletion
    functionRef:
      name: function-sequencer
    input:
      apiVersion: sequencer.fn.crossplane.io/v1beta1
      kind: Input
      enableDeletionSequencing: true
      replayDeletion: true
      rules:
        - sequence:
          - first-subresource-.*
          - second-resource
      usageVersion: v1
```

--------------------------------

### Handling Large Compositions with Regex

Source: https://github.com/crossplane-contrib/function-sequencer/blob/main/_autodocs/usage-patterns.md

Use regular expressions in sequences to manage large numbers of resources efficiently. Caching is recommended for performance with `cacheTTL`.

```yaml
rules:
  # All network-related resources must be ready
  - sequence:
      - ^network-.*
      - ^compute-.*
  # All compute resources must be ready before storage
  - sequence:
      - ^compute-.*
      - ^storage-.*
  # All storage must be ready before applications
  - sequence:
      - ^storage-.*
      - ^app-.*
```

--------------------------------

### Wrap Errors in Go

Source: https://github.com/crossplane-contrib/function-sequencer/blob/main/_autodocs/architecture.md

Demonstrates how to wrap errors with additional context in Go using the `errors.Wrap` function. This is useful for providing more information about the operation that failed.

```go
errors.Wrap(err, "context describing what was attempted")
```

--------------------------------

### Regex Group Matching for Resource Prerequisites

Source: https://github.com/crossplane-contrib/function-sequencer/blob/main/_autodocs/usage-patterns.md

Wait for all resources matching a regular expression pattern before proceeding with the next step in the sequence. This is useful for scenarios where multiple resources of a similar type (e.g., subnets across different availability zones) must be ready.

```yaml
rules:
  - sequence:
      - vpc
      - ^subnet-.*
      - compute-instance
```

--------------------------------

### Test Function Sequence with Crossplane CLI

Source: https://github.com/crossplane-contrib/function-sequencer/blob/main/README.md

Test a sequence using the Crossplane CLI's `render` command. The `--observed-resources` flag simulates pre-existing objects.

```sh
# --observed-resources allows you to simulate already created objects
crossplane render example/xr.yaml example/composition.yaml example/functions.yaml --observed-resources example/observed.yaml
```

--------------------------------

### Typical Usage Context in Function Sequencer

Source: https://github.com/crossplane-contrib/function-sequencer/blob/main/_autodocs/api-reference/name-generation.md

This snippet shows how GenerateName is integrated within the function-sequencer's generation process for Usage resources, combining resource details into a base name before hashing and appending a suffix.

```go
// From fn.go GenerateV2Usage()
name := strings.ToLower(by.GetKind() + "-" + by.GetName() + "-" + of.GetKind() + "-" + of.GetName())
usageMeta := map[string]any{
    "name": GenerateName(name, UsageNameSuffix), // UsageNameSuffix = "dependency"
}
```

--------------------------------

### Conditional Rules Sequencing with crossplane render

Source: https://github.com/crossplane-contrib/function-sequencer/blob/main/_autodocs/README.md

Use this command to apply sequencing rules based on conditional logic.

```bash
crossplane render example/xr.yaml example/composition-conditional.yaml example/functions.yaml
```

--------------------------------

### Run Delete-Only Mode Test

Source: https://github.com/crossplane-contrib/function-sequencer/blob/main/_autodocs/architecture.md

Execute a test for delete-only mode sequencing using `crossplane render`.

```bash
crossplane render example/xr.yaml example/composition-delete-only.yaml \
  example/functions.yaml
```

--------------------------------

### Run Regex Patterns Test

Source: https://github.com/crossplane-contrib/function-sequencer/blob/main/_autodocs/architecture.md

Execute a test involving regex patterns for sequencing, using `crossplane render`.

```bash
crossplane render example/xr.yaml example/composition-regex.yaml \
  example/functions.yaml
```

--------------------------------

### Common CEL Variables and Access Patterns

Source: https://github.com/crossplane-contrib/function-sequencer/blob/main/README.md

Illustrates common variables available in CEL condition expressions for accessing observed and desired states, and their typical usage patterns.

```cel
observed.composite.resource.spec.someField == "value"
desired.composite.resource.spec.count > 0
size(observed.resources) > 0
```

--------------------------------

### Deletion Sequencing Configuration

Source: https://github.com/crossplane-contrib/function-sequencer/blob/main/_autodocs/configuration.md

Enables deletion sequencing and replay for resources. Resources are created in the specified order, and deleted in the reverse order during composite deletion.

```yaml
- step: sequence-creation-and-deletion
  functionRef:
    name: function-sequencer
  input:
    apiVersion: sequencer.fn.crossplane.io/v1beta1
    kind: Input
    enableDeletionSequencing: true
    replayDeletion: true
    usageVersion: "v2"
    rules:
      - sequence:
          - vpc
          - subnet
          - instance
```

--------------------------------

### Deletion Sequencing Algorithm Logic

Source: https://github.com/crossplane-contrib/function-sequencer/blob/main/_autodocs/architecture.md

Details the deletion sequencing algorithm, which generates Usage resources for each dependency. It finds observed resources and creates Usage entries to define the deletion order.

```go
Generate Usage for each dependency:
  ├─ Find all observed resources matching C
  ├─ Find all observed resources matching B
  │  ├─ For each pair: create Usage(of: B, by: C)
  │  └─ Add to usages map
  ├─ Find all observed resources matching A
  │  ├─ For each pair: create Usage(of: A, by: B)
  │  └─ Add to usages map
```

--------------------------------

### Define Multi-Provider Composition Sequencing

Source: https://github.com/crossplane-contrib/function-sequencer/blob/main/_autodocs/usage-patterns.md

Define sequencing rules for compositions that span multiple cloud providers. This allows resources in one provider to depend on resources in another, enabling hybrid and multi-cloud architectures.

```yaml
rules:
  - sequence:
      - aws-vpc
      - aws-subnet
      - gcp-k8s-cluster
    # K8s cluster in GCP waits for AWS subnet (cross-provider dependency)
  - sequence:
      - gcp-k8s-cluster
      - azure-sql-database
```

--------------------------------

### Idempotence of GenerateName

Source: https://github.com/crossplane-contrib/function-sequencer/blob/main/_autodocs/api-reference/name-generation.md

Demonstrates the deterministic nature of the GenerateName function. The same input parameters will always result in the same output name, which is crucial for Kubernetes reconciliation.

```go
name1 := GenerateName("test", "suffix")
name2 := GenerateName("test", "suffix")
// name1 == name2 (always true)
```

--------------------------------

### RunFunction Signature

Source: https://github.com/crossplane-contrib/function-sequencer/blob/main/_autodocs/SUMMARY.txt

The signature for the RunFunction, which is the main entry point for the function service. It takes a context and a request, returning a Response and an error.

```Go
RunFunction(ctx, req) (*Response, error)
```

--------------------------------

### Delaying Resource Creation

Source: https://github.com/crossplane-contrib/function-sequencer/blob/main/_autodocs/errors.md

Resources matching a pattern are temporarily excluded from the desired state because their predecessor resource is not yet ready. These resources will be re-evaluated and included in the next reconciliation once the predecessor is ready.

```go
"Delaying creation of resource(s) matching \"<pattern>\" because \"<predecessor>\" does not exist yet" or "Delaying creation of resource(s) matching \"<pattern>\" because \"<predecessor>\" is not fully ready (<ready>/<desired>)"
```

--------------------------------

### Configure Function Input API Version

Source: https://github.com/crossplane-contrib/function-sequencer/blob/main/_autodocs/README.md

Specifies the API version for configuring the function's input. This beta API may change in future releases.

```yaml
apiVersion: sequencer.fn.crossplane.io/v1beta1
kind: Input
```

--------------------------------

### GenerateV1Usage Function

Source: https://github.com/crossplane-contrib/function-sequencer/blob/main/_autodocs/api-reference/function.md

Creates a v1 Usage resource for cluster-scoped resources. Namespaced resources will result in an error. The resource references the dependency and sets the reason to 'dependency'.

```go
func GenerateV1Usage(
    of, by *unstructured.Unstructured,
    rd bool,
) map[string]any
```

--------------------------------

### Enable Deletion Sequencing with Explicit Rules

Source: https://github.com/crossplane-contrib/function-sequencer/blob/main/README.md

This snippet shows how to enable deletion sequencing with explicit resource ordering rules. Set `enableDeletionSequencing` to true and define the desired deletion order in the `rules.sequence` field. Ensure foreground cascading deletion is used when deleting the composite resource.

```yaml
  - step: sequence-creation-and-deletion
    functionRef:
      name: function-sequencer
    input:
      apiVersion: sequencer.fn.crossplane.io/v1beta1
      kind: Input
      enableDeletionSequencing: true
      replayDeletion: true
      rules:
        - sequence:
          - first
          - second
          - third
      usageVersion: v1
```

--------------------------------

### Regex Patterns for Sequencing

Source: https://github.com/crossplane-contrib/function-sequencer/blob/main/_autodocs/README.md

Allows using regex patterns for resource names to match groups, ensuring all matching resources are ready before proceeding.

```yaml
rules:
  - sequence: [vpc, "^subnet-.*", instance]
```

--------------------------------

### TLS Certificate Directory Structure

Source: https://github.com/crossplane-contrib/function-sequencer/blob/main/_autodocs/api-reference/cli.md

Illustrates the required file structure within the TLS directory for the function-sequencer, including CA certificate, server certificate, and private key.

```text
/etc/crossplane/function-certs/
├── ca.crt        (CA certificate to verify client certificates)
├── tls.crt       (Server certificate signed by CA)
└── tls.key       (Server private key)
```

--------------------------------

### RunFunctionResponse Structure

Source: https://github.com/crossplane-contrib/function-sequencer/blob/main/_autodocs/types.md

Outlines the structure of the RunFunctionResponse, focusing on the desired state and modified resources.

```go
RunFunctionResponse
└── Desired: State
    └── Resources: map[resource.Name]*resource.DesiredComposed
        (modified by function, includes generated Usages)
```

--------------------------------

### Multi-Level Dependency Chain

Source: https://github.com/crossplane-contrib/function-sequencer/blob/main/_autodocs/usage-patterns.md

Defines a sequential creation order for resources, where each subsequent resource depends on the readiness of the previous one. Supports ordered deletion when enabled.

```yaml
rules:
  - sequence:
      - vpc
      - subnet
      - security-group
      - instance
```

--------------------------------

### Cascading Dependencies in Resource Sequencing

Source: https://github.com/crossplane-contrib/function-sequencer/blob/main/_autodocs/usage-patterns.md

Define a sequence where resources are prerequisites for subsequent ones. The sequencer ensures that 'subnet' is created only after 'vpc' is ready, and 'nat-gateway' only after 'subnet' is ready.

```yaml
rules:
  - sequence:
      - vpc
      - subnet
  - sequence:
      - subnet
      - nat-gateway
```

--------------------------------

### Response Caching Strategy

Source: https://github.com/crossplane-contrib/function-sequencer/blob/main/_autodocs/architecture.md

Illustrates the response caching mechanism where input configuration hashes are mapped to cached outputs with a Time-To-Live (TTL). This prevents redundant function invocations if Crossplane reconciles within the TTL.

```text
Input config (Hash) → Cached Output (TTL)
```

--------------------------------

### Define Sequencing Rule Structure

Source: https://github.com/crossplane-contrib/function-sequencer/blob/main/_autodocs/types.md

Defines a single sequencing rule for managing resource dependencies. Use this to specify the order of resources and optional conditions for creation or deletion.

```Go
type SequencingRule struct {
    // Sequence is the ordered list of resource names/patterns
    Sequence []resource.Name
    
    // Condition is a CEL expression; when false, creation is skipped
    Condition string
    
    // DeleteOnly skips creation sequencing, only enforces deletion order
    DeleteOnly bool
}
```

--------------------------------

### Kubernetes Resource Name Generation Logic

Source: https://github.com/crossplane-contrib/function-sequencer/blob/main/_autodocs/architecture.md

Details the process for generating unique and Kubernetes-compliant names for resources, including hashing and truncation to meet the 63-character limit.

```text
Input: of={kind,name,namespace}, by={kind,name}

1. Construct descriptive name:
   base = "by-kind-by-name-of-kind-of-name" (lowercased)

2. Hash the base:
   hash = SHA256(base)[:6] (6 hex chars)

3. Construct suffix:
   suffix = "hash-dependency"

4. Build full name:
   fullName = base + "-" + suffix

5. Enforce Kubernetes limit:
   if len(fullName) > 63:
      truncate base to fit
      ensure no trailing "-"
   return truncated-name + suffix
```

--------------------------------

### Generate Observed Usages

Source: https://github.com/crossplane-contrib/function-sequencer/blob/main/_autodocs/api-reference/function.md

Creates Usage or ClusterUsage resources for observed resources to preserve deletion order. This function processes dependency pairs in the sequence and generates Usage resources with 'by: dependent' and 'of: predecessor' fields. It runs regardless of CEL condition evaluation.

```go
error := f.generateObservedUsages(sequence, observedComposed, desiredComposed, usages, replayDeletion, usageVersion)
```

--------------------------------

### Define Function Input Structure

Source: https://github.com/crossplane-contrib/function-sequencer/blob/main/_autodocs/types.md

Defines the main configuration object passed to the function. Use this to set cache TTL, control deletion sequencing, specify replay behavior, and define sequencing rules.

```Go
type Input struct {
    metav1.TypeMeta
    metav1.ObjectMeta
    
    // CacheTTL sets response cache time-to-live (default "1m")
    CacheTTL string
    
    // EnableDeletionSequencing controls creation of Usage/ClusterUsage resources
    EnableDeletionSequencing bool
    
    // ReplayDeletion sets the replayDeletion attribute on Usage resources (default true)
    ReplayDeletion bool
    
    // UsageVersion specifies API version for generated usages: "v1" or "v2" (default "v2")
    UsageVersion UsageVersion
    
    // ResetCompositeReadiness sets composite Ready to False when resources are removed
    ResetCompositeReadiness bool
    
    // Rules is the list of sequencing rules
    Rules []SequencingRule
}
```

--------------------------------

### Recommended Cache TTL for Stable Compositions

Source: https://github.com/crossplane-contrib/function-sequencer/blob/main/_autodocs/usage-patterns.md

Set a longer `cacheTTL` for stable compositions to improve performance by avoiding repeated regex evaluations.

```yaml
cacheTTL: "5m"  # Longer for stable compositions
```

--------------------------------

### V1 Mode Incompatible with Namespaced Resources

Source: https://github.com/crossplane-contrib/function-sequencer/blob/main/_autodocs/errors.md

When `usageVersion: "v1"` is configured, the sequencer cannot protect namespaced resources. This mode only supports cluster-scoped resources. For namespaced resources, use `usageVersion: "v2"` or remove them from the composition.

```yaml
usageVersion: "v1"  # v1 mode
# Composition includes a namespaced resource:
apiVersion: v1
kind: Service
metadata:
  namespace: default  # Namespaced!
```