Node Executors

Relevant source files

• internal/tools/mproc/sender.go
• internal/workflow/engine/context.go
• internal/workflow/engine/engine.go
• internal/workflow/engine/executor_bizapply.go
• internal/workflow/engine/executor_bizdeploy.go
• internal/workflow/engine/executor_bizmonitor.go
• internal/workflow/engine/executor_biznotify.go
• internal/workflow/engine/executor_bizupload.go
• internal/workflow/engine/executor_condition.go
• internal/workflow/engine/executor_trycatch.go
• internal/workflow/engine/state.go

Node Executors are the functional units of the Certimate workflow engine. Each executor is responsible for a specific stage of the certificate lifecycle, ranging from ACME issuance and deployment to monitoring and notification. They operate within a NodeExecutionContext internal/workflow/engine/context.go7-17 and return a NodeExecutionResult internal/workflow/engine/executor.go17-25 which the engine uses to update the global VariableManager and InOutManager.

Core Executor Architecture

All executors implement the NodeExecutor interface internal/workflow/engine/executor.go10-15 and typically embed the nodeExecutor base struct to inherit logging and common repository access. The engine maps NodeType constants internal/domain/workflow.go91-105 to specific implementations during the Invoke process internal/workflow/engine/engine.go61-99

Data Flow and State

Executors interact with two primary state managers:

1. VariableManager: Stores key-value pairs (e.g., certificate.daysLeft) used for template rendering and condition evaluation internal/workflow/engine/state.go37-50
2. InOutManager: Manages artifacts (like certificate IDs) passed between nodes via references internal/workflow/engine/state.go180-189

Mapping Node Types to Code Entities

The following diagram bridges the workflow configuration names to their corresponding Go implementation structs and logic.

Executor Implementation Map

Sources: internal/workflow/engine/executor_bizapply.go54-60 internal/workflow/engine/executor_bizdeploy.go21-27 internal/workflow/engine/executor_bizmonitor.go31-35 internal/workflow/engine/executor_biznotify.go15-19 internal/workflow/engine/executor_bizupload.go36-41 internal/workflow/engine/executor_delay.go11-13 internal/workflow/engine/executor_condition.go11-13 internal/workflow/engine/executor_trycatch.go11-13

---

1. bizApply (ACME Certificate Request)

The bizApplyNodeExecutor handles the automated issuance of certificates via ACME.

Key Features

• Multi-Process Isolation: By default, ACME requests are executed in a separate process using the mproc package to prevent memory leaks or crashes in the main process from third-party ACME libraries. This behavior is controlled by the CERTIMATE_WORKFLOW_MULTIPROC environment variable internal/workflow/engine/executor_bizapply.go27-31 The Sender in mproc handles encrypted IPC via temporary files internal/tools/mproc/sender.go33-185
• Skip Logic: It compares the current configuration with the lastOutput (saved in workflow_output). If domains, providers, or keys haven't changed and the certificate is still valid, it skips the request internal/workflow/engine/executor_bizapply.go159-210
• ARI (Acme Renewal Information): Supports ARI to determine if a certificate should be replaced based on CA recommendations. If replaced, it updates the IsRenewed status of the previous certificate internal/workflow/engine/executor_bizapply.go127-131

Execution Flow

Sources: internal/workflow/engine/executor_bizapply.go62-138 internal/workflow/engine/executor_bizapply.go237-250 internal/tools/mproc/sender.go83-95

---

2. bizDeploy (Certificate Push)

The bizDeployNodeExecutor pushes a certificate to a target provider (e.g., Alibaba Cloud, AWS, SSH).

• Input Retrieval: It fetches the certificate from a previous node's output using a reference string (e.g., nodeId#certId) stored in the InOutManager internal/workflow/engine/executor_bizdeploy.go46-60
• Skip-on-Last-Succeeded: If enabled via SkipOnLastSucceeded, the node will skip deployment if the previous run of this specific node succeeded and the input certificate hasn't been updated since that run internal/workflow/engine/executor_bizdeploy.go121-141
• Implementation: Uses certmgmt.NewClient to perform the actual deployment via the DeployCertificate method internal/workflow/engine/executor_bizdeploy.go92-103

Sources: internal/workflow/engine/executor_bizdeploy.go29-110

---

3. bizUpload (Manual PEM Import)

The bizUploadNodeExecutor allows importing existing certificates into the workflow.

• Sources: Supports form (direct text), local (file path), and url (HTTP GET via resty) internal/workflow/engine/executor_bizupload.go87-133
• Validation: Automatically parses the PEM using xcert.ParseCertificateFromPEM internal/workflow/engine/executor_bizupload.go144-146 and verifies the public key matches the provided private key using RSA, ECDSA, or Ed25519 equality checks internal/workflow/engine/executor_bizupload.go151-174
• Persistence: Saves the imported certificate to the certificate collection with source type CertificateSourceTypeUpload internal/workflow/engine/executor_bizupload.go177-189

Sources: internal/workflow/engine/executor_bizupload.go49-197

---

4. bizMonitor (TLS Health Check)

The bizMonitorNodeExecutor performs a live TLS handshake with a target host to verify the deployed certificate.

• Retries: Performs up to 3 attempts with a 2-second interval internal/workflow/engine/executor_bizmonitor.go55-75
• Validation: Checks if the certificate is within its validity period and if the hostname matches the certificate's SANs/CommonName using cert.VerifyHostname internal/workflow/engine/executor_bizmonitor.go94-115
• Output Variables: Populates variables like certificate.daysLeft and certificate.validity for use in subsequent condition nodes internal/workflow/engine/executor_bizmonitor.go160-192

Sources: internal/workflow/engine/executor_bizmonitor.go37-120

---

5. bizNotify (Templated Alerts)

The bizNotifyNodeExecutor sends alerts via configured channels (Email, Telegram, Matrix, etc.).

• Template Rendering: Uses a regex-based mustache replacer to inject variables. It supports global variables (e.g., {{ $run.id }}) and special variables like {{ $now }} internal/workflow/engine/executor_biznotify.go44-66
• Skip Logic: Can be configured to skip if all previous nodes in the workflow were skipped (SkipOnAllPrevSkipped) by checking the stateVarKeyNodeSkipped variable across all scopes internal/workflow/engine/executor_biznotify.go86-106

Sources: internal/workflow/engine/executor_biznotify.go21-84

---

6. Logic & Flow Control Nodes

condition & branchBlock

The conditionNodeExecutor acts as a container for multiple branchBlock nodes internal/workflow/engine/executor_condition.go15-49

• Evaluation: Each branchBlock evaluates a string-based expression using the Expression.Eval method internal/workflow/engine/executor_condition.go78-82
• Variable Scope: All current workflow variables are converted to strings via ValueString() and passed to the evaluator as a map internal/workflow/engine/executor_condition.go68-76

tryCatch

The tryCatchNodeExecutor provides error handling internal/workflow/engine/executor_trycatch.go15-70

• Flow: It first executes nodes in the try block. If any node returns an error, it proceeds to execute the catch block. If errors occur in the try block, it returns an ErrBlocksException internal/workflow/engine/executor_trycatch.go25-67

delay

The delayNodeExecutor pauses execution for a configurable duration in seconds. It uses xwait.DelayWithContext to ensure the wait is interruptible if the workflow context is cancelled internal/workflow/engine/executor_delay.go15-24

Sources: internal/workflow/engine/executor_condition.go11-101 internal/workflow/engine/executor_trycatch.go11-130 internal/workflow/engine/executor_delay.go11-24