Net Endpoint

Net Endpoint creates and starts network protocol servers with support for multiple protocols and packet processing modes. Ideal for IoT device connectivity, sensor data collection, network protocol proxying, and real-time data processing.

# Type

endpoint/net

# Core Features

# 🌐 Multi-Protocol Support

TCP/UDP: Standard network protocols
IPv4/IPv6: Support for ip4:1, ip6:ipv6-icmp, ip6:58, etc.
Unix Socket: unix, unixgram local communication
Extended Protocols: All protocol types supported by Go's net package

# 📦 Smart Packet Splitting

line: Split by newlines (\n or \r\n) - default mode
fixed: Fixed-length splitting
delimiter: Custom delimiter (supports hex format)
length_prefix: Length-prefix mode (supports endianness, includes/excludes prefix length)

# 🔄 Data Type Processing

Default Behavior: All network data defaults to BINARY type to preserve data integrity.

Type Conversion: Change data type using built-in processors:

// Use processors in router configuration
router := impl.NewRouter().From("").
  Process("setJsonDataType").    // Set to JSON type
  To("chain:jsonProcessor").End()

1
2
3
4

Available Processors:

setJsonDataType: For JSON APIs and REST services
setTextDataType: For text-based protocols (HTTP, SMTP, etc.)
setBinaryDataType: Explicitly set to binary (default)

# ⚡ Hot Reload Support

Supports rule chain hot reloading without server restart to update processing logic.

# Configuration

Field	Type	Required	Description	Default
protocol	string	No	Network protocol: tcp/udp/unix, etc.	tcp
server	string	Yes	Server address in host:port format, e.g., ":8888"	-
readTimeout	int	No	Read timeout in seconds, 0 for no timeout	60
packetMode	string	No	Packet splitting mode	line
packetSize	int	No	Packet size (meaning varies by mode)	0
delimiter	string	No	Custom delimiter (supports 0x0A hex format)	-
maxPacketSize	int	No	Maximum packet size to prevent malicious attacks	64KB
encode	string	No	hex/base64 encode bytes to string; text/string/json set dataType only (no encoding, readable by editor/downstream)	-
sessionKey	string	No	Session addressing key extraction rule (rulego `${}` expression). E.g. `${msg.deviceId}` extracts deviceId from first frame; empty uses RemoteAddr	-
sessionTTL	int	No	Session idle TTL (seconds). When idle beyond this duration the connection is closed so the device reconnects and the sessionKey is re-extracted; <=0 uses default 1800	1800

# Session Addressing & Active Push

endpoint/net has a built-in session registry maintaining a Session for each connected device. Combined with sender nodes (net/ws in ref:// mode), you can reuse the device's established long connection to actively push data to a specific device by deviceId/IP, without polling or extra connections.

# sessionKey extraction

sessionKey uses a rulego ${} expression to extract the session key from the data reported by the device (the first frame usually carries identity). Timing: it attempts extraction on every received frame after connection and is fixed after the first success (subsequent frames do not override), ensuring a stable session key.

Common configs:

${msg.deviceId}: deviceId field of a JSON first frame
${msg.header.sn}: nested field
${hex(data[4:14])}: binary protocol, hex of bytes at offset 4-14 as the key
${reFind("ID:([a-zA-Z0-9_]+)", data)}: regex extraction (must use double quotes, el engine doesn't accept single quotes; avoid \w, use [a-zA-Z0-9_])
empty: defaults to the device RemoteAddr (IP:Port)

# Active push

After the device connects and the sessionKey is extracted, use a net node (server=ref://<this endpoint instance ID>, target=deviceId or *) to push to a specific device or all devices. See net component - Session Addressing Push.

// endpoint/net configures sessionKey
ep.Init(config, types.Configuration{
    "server":     ":8080",
    "sessionKey": "${msg.deviceId}",
})
// net node ref:// addressing push: server=ref://<endpoint/net instance ID>, target=DEV_001 or *

1
2
3
4
5
6

# Packet Splitting Modes

# Line Mode (Default)

{
  "packetMode": "line"
}

1
2
3

Suitable for text protocols, splits by \n or \r\n.

# Fixed Mode

{
  "packetMode": "fixed",
  "packetSize": 16
}

1
2
3
4

Fixed-length packets, suitable for binary protocols.

# Delimiter Mode

{
  "packetMode": "delimiter",
  "delimiter": "0x0D0A"
}

1
2
3
4

Custom delimiter, supports hex format.

# Length Prefix Mode

{
  "packetMode": "length_prefix_be",
  "packetSize": 2,
  "maxPacketSize": 4096
}

1
2
3
4
5

Length-prefix protocols, supports:

length_prefix_le: Little endian, length excludes prefix
length_prefix_be: Big endian, length excludes prefix
length_prefix_le_inc: Little endian, length includes prefix
length_prefix_be_inc: Big endian, length includes prefix

# Router Configuration

# Recommended Configuration (Single Router Mode)

// Simple configuration
router := impl.NewRouter().From("").To("chain:main").End()
ep.AddRouter(router)

// With data type processor
router := impl.NewRouter().From("").
  Process("setJsonDataType").
  To("chain:jsonProcessor").End()
ep.AddRouter(router)

1
2
3
4
5
6
7
8
9

# Advanced Router Configuration

// Router matching options
options := &net.RouterMatchOptions{
  MatchRawData:   true,           // Match raw data
  DataTypeFilter: "JSON",         // Data type filter
  MinDataLength:  10,             // Minimum data length
  MaxDataLength:  1024,           // Maximum data length
}
router := impl.NewRouter().From("^sensor.*").To("chain:sensor").End()
routerId, err := ep.AddRouter(router, options)

1
2
3
4
5
6
7
8
9

# Complete Configuration Examples

# IoT Sensor Gateway

{
  "id": "iot_gateway",
  "type": "endpoint/net", 
  "configuration": {
    "protocol": "tcp",
    "server": ":8080",
    "packetMode": "length_prefix_be",
    "packetSize": 2,
    "maxPacketSize": 1024,
    "readTimeout": 30
  },
  "routers": [
    {
      "from": {
        "path": ".*",
        "processors": ["setBinaryDataType"]
      },
      "to": {
        "path": "chain:iotProcessor"
      }
    }
  ]
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

# JSON API Server

{
  "id": "json_api", 
  "type": "endpoint/net",
  "configuration": {
    "protocol": "tcp",
    "server": ":9090",
    "packetMode": "line",
    "readTimeout": 60
  },
  "routers": [
    {
      "from": {
        "path": ".*",
        "processors": ["setJsonDataType"]
      },
      "to": {
        "path": "chain:apiProcessor"
      }
    }
  ]
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

# UDP Broadcast Receiver

{
  "id": "udp_receiver",
  "type": "endpoint/net",
  "configuration": {
    "protocol": "udp", 
    "server": ":8888",
    "maxPacketSize": 2048
  },
  "routers": [
    {
      "from": {
        "path": ".*",
        "processors": ["setTextDataType"]
      },
      "to": {
        "path": "chain:udpProcessor"
      }
    }
  ]
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

# Hot Reload Example

// Initial DSL configuration
initialDSL := `{
  "ruleChain": {
    "id": "iotProcessor", 
    "root": true
  },
  "metadata": {
    "endpoints": [...],
    "nodes": [...]
  }
}`

// Start rule engine
ruleEngine, _ := rulego.New("iotProcessor", []byte(initialDSL))

// Hot reload configuration
updatedDSL := `{...}` // New configuration
err := ruleEngine.ReloadSelf([]byte(updatedDSL))

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

# Use Cases

# 🏭 Industrial IoT

Sensor data collection
PLC device communication
Modbus TCP proxy

# 🌐 Network Services

TCP/UDP proxy
Protocol conversion gateway
Real-time data streaming

# 📡 Device Connectivity

MQTT gateway
Device registration service
Heartbeat monitoring

# Best Practices

Data Type Selection
- IoT sensors: Keep BINARY type for data integrity
- JSON APIs: Use setJsonDataType processor
- Text protocols: Use setTextDataType processor
Router Design
- Recommend single default router, handle complex logic in rule chains
- Avoid excessive regex routes
Performance Optimization
- Set appropriate maxPacketSize to prevent malicious attacks
- Configure proper readTimeout to avoid connection hogging
Security Considerations
- Limit server binding address in production environments
- Use firewall to restrict access sources

# Example Code

Complete examples:

Edit this page on GitHub

Last Updated: 2026/07/29, 10:24:31

← Schedule Endpoint Kafka Endpoint→