1.2.3 JNPL Syntax

JNet Packet Language (JNPL) Wiki

Welcome to the JNet Packet Language (JNPL) Wiki! This documentation provides a comprehensive overview of JNPL, a domain-specific language designed for defining and managing network packet processing rules. Whether you're a developer, network engineer, or enthusiast, this guide will help you understand, implement, and extend JNPL effectively.

Introduction

JNet Packet Language (JNPL) is a powerful and flexible language tailored for defining network packet processing rules. It allows users to create detailed filters, actions, and hash modes to manage and distribute network traffic efficiently. By leveraging explicit data types, modular syntax, and robust grammar, JNPL ensures clarity, maintainability, and scalability in complex networking environments.

Key Features

Explicit Data Types: Clear definitions for byte streams, offsets, lengths, ranges, and sets.
Modular Protocol Definitions: Organize protocols and sub-protocols with conditional logic.
Flexible Hash Modes: Define sophisticated hash distribution mechanisms.
Array Accessors: Handle multiple MPLS labels and VLAN tags using both constants and negative indices.
Best Practices Integration: Guidelines for writing clean, efficient, and maintainable scripts.
Tooling Support: Syntax highlighting, linters, and formatters to enhance the development experience.
Community-Driven: Open-source repository fostering collaboration and continuous improvement.

Data Types

Establishing clear data types is crucial for maintaining consistency and ensuring that JNPL scripts are both readable and less error-prone. Below are the primary data types used in JNPL:

1. Byte Stream

Description: Represents an array of bytes.
Syntax: reference[offset:length]
Defaults:
- If offset is omitted, it defaults to 0.
- If length is omitted, it defaults to the remaining bytes from offset.

Examples:

Packet[0:10]     // Bytes 0 to 9 of Packet
Packet[:10]      // Bytes 0 to 9 of Packet (offset defaults to 0)
Packet[10:]      // Bytes 10 to the end of Packet (length defaults to remaining bytes)

2. Offset

Description: Specifies the byte or bit offset within a byte stream.
Type: Integer
Usage: Indicates the starting position for data extraction or manipulation.
Example:
```
Offset: Packet.L3Offset >> 2
```

3. Length

Description: Specifies the number of bytes or bits to process.
Type: Integer
Usage: Indicates the size of the data segment to extract or manipulate.
Example:
```
Length: Packet.L3Len >> 2
```

4. Range

Description: Combines offset and length to define a specific segment within a byte stream.
Syntax: offset:length
Type: Derived from Offset and Length
Usage: Used for defining segments like Payload.

Example:

Payload: 12:64    // Starts at byte 12 and spans 64 bytes

5. Set

Description: Represents a collection of discrete values.
Syntax: A,B,C,...
Type: Enumeration
Usage: Used for conditions and selections.
Example:
```
Layer3.Type in [IPv4, IPv6]
```

Syntax and Protocol Definitions

JNPL's syntax is designed to be both expressive and intuitive, allowing users to define complex network processing rules with ease. Key aspects include:

1. Implicit Type Definitions

Use : instead of = to define implicit types without using the define statement.

Before:
```
Offset = Packet.L3Offset >> 2
```
After:
```
Offset: Packet.L3Offset >> 2
```

2. Dot Notation for Field Access

Access fields using . instead of [], except when accessing array elements or performing logical evaluations.

Example:
```
MPLS[TopLabel].Id == 100
```

3. Array Accessors with Constants and Negative Indices

Handle multiple MPLS labels and VLAN tags using array accessors ([]) with both numeric constants and predefined indices.

Constants Definition:

define TopLabel 0
define BottomLabel -1

Usage:

MPLS[TopLabel].Id == 100
MPLS[BottomLabel].Label == 200

4. Protocol Block Structure

Organize protocols and sub-protocols with conditional logic and field definitions.

Example:

define IP protocol {
    Offset: Packet.L3Offset >> 2
    Length: Packet.L3Len >> 2
    Payload: Packet.length - (Offset + Length)

    fields: { Src, Dst, TTL, Protocol }

    // Define IPv4 Sub-Protocol
    define IPv4 protocol {
        condition: Packet.L3Type == IPv4
        fields: { Src = 12:4, Dst = 16:4, Flags = 6, TTL = 8, Protocol = 9 }
    }

    // Define IPv6 Sub-Protocol
    define IPv6 protocol {
        condition: Packet.L3Type == IPv6
        fields: { Src = 7:16, Dst = 23:6, FlowLabel = 1, TTL = 6, Protocol = 5 }
    }
}

Grammar Specification

Formalizing the grammar of JNPL using Extended Backus-Naur Form (EBNF) ensures consistency and facilitates the development of parsers, linters, and other tooling.

Revised EBNF for JNPL

<JNPL> ::= <Statement>+

<Statement> ::= <DefineProtocolBlock>
              | <DefineHashMode>
              | <DefineConstant>
              | <DefineFilter>
              | <DefineAction>
              | <OtherStatements>

<DefineProtocolBlock> ::= 'protocol' '{' <ProtocolBlock>+ '}'

<ProtocolBlock> ::= 'define' <Identifier> 'protocol' '{' <ProtocolOptions> <SubProtocol>+ '}'

<SubProtocol> ::= 'define' <Identifier> 'protocol' '{' <SubProtocolOptions> '}'

<ProtocolOptions> ::= <ProtocolOption>+

<ProtocolOption> ::= 'Offset:' <Expression>
                  | 'Length:' <Expression>
                  | 'Payload:' <Expression>
                  | 'fields:' '{' <FieldList> '}'

<SubProtocolOptions> ::= <SubProtocolOption>+

<SubProtocolOption> ::= 'condition:' <Condition>
                      | 'fields:' '{' <FieldAssignments> '}'

<FieldList> ::= <FieldName> { ',' <FieldName> }

<FieldAssignments> ::= <FieldAssignment> { ',' <FieldAssignment> }

<FieldAssignment> ::= <FieldName> '=' <OffsetLength>

<Condition> ::= <Expression>

<DefineHashMode> ::= 'define' <Identifier> 'HashMode' '{' <HashModeOption>+ '}'

<HashModeOption> ::= 'Priority' '=' <Integer>
                   | 'Encapsulation' '=' <EncapsulationList>
                   | 'Layer3Type' '=' <Layer3TypeList>
                   | 'Layer4Type' '=' <Layer4TypeList>
                   | 'InnerLayer3Type' '=' <InnerLayer3TypeList>
                   | 'InnerLayer4Type' '=' <InnerLayer4TypeList>
                   | 'TupleSwap' '=' <TrueFalse>
                   | 'MaskNo' '=' <Integer>
                   | 'Port' '=' <PortNumberSpec>
                   | 'Algorithm' '=' <HashAlgorithm>
                   | 'Key' '=' <HexString>
                   | 'Tag' '=' <Identifier>

<EncapsulationList> ::= <EncapsulationValue> { ',' <EncapsulationValue> }
<EncapsulationValue> ::= 'VLAN' | 'MPLS'

<Layer3TypeList> ::= <Layer3TypeValue> { ',' <Layer3TypeValue> }
<Layer3TypeValue> ::= 'IPv4' | 'IPv6' | 'IP' | 'Other'

<Layer4TypeList> ::= <Layer4TypeValue> { ',' <Layer4TypeValue> }
<Layer4TypeValue> ::= 'TCP' | 'UDP' | 'ICMP' | 'GREv0' | 'SCTP' | 'Other'

<InnerLayer3TypeList> ::= <InnerLayer3TypeValue> { ',' <InnerLayer3TypeValue> }
<InnerLayer3TypeValue> ::= 'IPv4' | 'IPv6' | 'IP' | 'Other'

<InnerLayer4TypeList> ::= <InnerLayer4TypeValue> { ',' <InnerLayer4TypeValue> }
<InnerLayer4TypeValue> ::= 'TCP' | 'UDP' | 'SCTP' | 'Other'

<HashAlgorithm> ::= 'CRC32' | 'SHA256' | 'NTH10' | 'TOEPLITZ' | 'HashRoundRobin'

<HexString> ::= '0x' <HexDigits>
<HexDigits> ::= <HexDigit>+

<HexDigit> ::= '0' | '1' | '2' | '3' | '4' | '5' | '6' | '7' | '8' | '9'
             | 'A' | 'B' | 'C' | 'D' | 'E' | 'F'
             | 'a' | 'b' | 'c' | 'd' | 'e' | 'f'

<PortNumberSpec> ::= '"' <AnyCharacterExceptDoubleQuote>* '"'

<Identifier> ::= <Letter> { <Letter> | <Digit> | '_' }

<Letter> ::= 'A'..'Z' | 'a'..'z'

<Integer> ::= <Digit>+

<Digit> ::= '0'..'9'

<String> ::= '"' { <AnyCharacterExceptDoubleQuote> } '"'

<TrueFalse> ::= 'true' | 'false'

<Expression> ::= <FieldAccess> <Operator> <Value>

<FieldAccess> ::= <Identifier> ( '[' <Index> ']' )? '.' <FieldName>

<Index> ::= <Identifier> | <Integer>

<Operator> ::= '==' | '!=' | '<=' | '>=' | '<' | '>' | 'in' | 'AND' | 'OR'

<Value> ::= <Identifier> | <Integer> | <String> | '[' <ValueList> ']'

<ValueList> ::= <Value> { ',' <Value> }

Key Enhancements

Array Accessors with Constants and Negative Indices: Supports accessing array elements using both predefined constants (e.g., TopLabel) and negative indices (e.g., -1 for the most inner label/tag).
Dot Notation: Utilizes dot notation for nested field access after indexing with brackets.
Reserved Bracket Notation: Maintains bracket notation for array indexing and list-based conditions.
Conditional Logic: Integrates conditional expressions within protocol and sub-protocol definitions.

Example Scripts

To illustrate how the enhanced JNPL syntax and data types are applied, here are comprehensive example scripts demonstrating multiple MPLS labels and VLAN tags, along with protocol and action definitions.

Comprehensive JNPL Script

priority = 10

define TopLabel 0
define BottomLabel -1

// Supported Protocols and Fields
protocol {
    // Define IP Protocol Block
    define IP protocol {
        Offset: Packet.L3Offset >> 2
        Length: Packet.L3Len >> 2
        Payload: Packet.length - (Offset + Length)

        fields: { Src, Dst, TTL, Protocol }

        // Define IPv4 Sub-Protocol
        define IPv4 protocol {
            condition: Packet.L3Type == IPv4
            fields: { Src = 12:4, Dst = 16:4, Flags = 6, TTL = 8, Protocol = 9 }
        }

        // Define IPv6 Sub-Protocol
        define IPv6 protocol {
            condition: Packet.L3Type == IPv6
            fields: { Src = 7:16, Dst = 23:6, FlowLabel = 1, TTL = 6, Protocol = 5 }
        }
    }

    // Define TRANSPORT Protocol Block
    define TRANSPORT protocol {
        Offset: Packet.L4Offset >> 2
        Length: Packet.L4Len >> 2
        Payload: Packet.length - (Offset + Length)

        fields: { SrcPort, DstPort, Length, Checksum }

        // Define TCP Sub-Protocol
        define TCP protocol {
            condition: Packet.L4Type == TCP
            fields: { SrcPort = 0:2, DstPort = 2:2, Flags = 12:2, Seq = 4:4, Ack = 8:4, Checksum = 16:2 }
        }

        // Define UDP Sub-Protocol
        define UDP protocol {
            condition: Packet.L4Type == UDP
            fields: { SrcPort = 0:2, DstPort = 2:2, Length = 4:2, Checksum = 6:2 }
        }

        // Define SCTP Sub-Protocol
        define SCTP protocol {
            condition: Packet.L4Type == SCTP
            fields: { SrcPort = 0:2, DstPort = 2:2, Tag = 4:4, Checksum = 8:4 }
        }

        // Add more transport protocols as needed
    }

    // Define APPLICATION Protocol Block
    define APPLICATION protocol {
        Offset: Packet.L5Offset >> 2
        Length: Packet.L5Len >> 2
        Payload: Packet.length - (Offset + Length)

        fields: { AppSrc, AppDst, AppType }

        // Define HTTP Sub-Protocol
        define HTTP protocol {
            condition: Packet.L5Type == HTTP
            fields: { AppSrc = 0:2, AppDst = 2:2, Method = 4:4, StatusCode = 8:4 }
        }

        // Define HTTPS Sub-Protocol
        define HTTPS protocol {
            condition: Packet.L5Type == HTTPS
            fields: { AppSrc = 0:2, AppDst = 2:2, Method = 4:4, StatusCode = 8:4 }
        }

        // Add more application protocols as needed
    }
}

// Define Constants
define TCP 17
define UDP 8
define IPv4 1
define IPv6 2
define HTTP 80
define HTTPS 443

// HashMode Definitions using define/block Style
define Hash5Tuple HashMode {
    Priority = 5
    Encapsulation = VLAN,MPLS
    Algorithm = CRC32
    Key = 0xABCDEF
    Tag = VlanTag
}

define Hash3TupleGTPv1v2Sorted HashMode {
    Priority = 10
    Encapsulation = VLAN
    Layer3Type = IPv4,IPv6
    Layer4Type = TCP,UDP
    Algorithm = SHA256
}

// Filter Definition for VLAN Traffic
define VLAN_TRAFFIC filter {
    Frame[4:2] == IPv4
    MPLS[TopLabel].Id == 100 AND MPLS[BottomLabel].Label == 200
    VLAN[TopLabel].Id == 100 AND VLAN[BottomLabel].Id == 200 AND VLAN.Count >= 2 AND VLAN.Payload == 3
    Layer3.Type in [IPv4, IPv6]
    Layer4.Type == TCP
    Port == 4
}

// Action Definition for VLAN Traffic using Hash5Tuple
action HandleVLANTraffic {
    filter VLAN_TRAFFIC == true

    log "SYN packet from 192.168.1.1 detected"
    distribute = (0..3) based on Hash5Tuple

    slice = 12:64
}

// Additional Action Definition using Hash3TupleGTPv1v2Sorted
action DistributeWithHash3Tuple {
    filter SomeOtherFilter == true

    log "Distributing traffic based on Hash3TupleGTPv1v2Sorted"
    distribute = (0..3) based on Hash3TupleGTPv1v2Sorted

    slice = 20:128
}

Explanation of the Example Script

Protocol Definitions:
- IP Protocol Block: Handles both IPv4 and IPv6 sub-protocols.
- TRANSPORT Protocol Block: Manages TCP, UDP, and SCTP sub-protocols.
- APPLICATION Protocol Block: Defines HTTP and HTTPS sub-protocols.
Constants:
- Defines numeric constants for protocols and ports, enhancing readability and maintainability.
HashMode Definitions:
- Hash5Tuple: Utilizes VLAN and MPLS encapsulations with the CRC32 algorithm.
- Hash3TupleGTPv1v2Sorted: Uses VLAN encapsulation with the SHA256 algorithm.
Filter Definitions:
- VLAN_TRAFFIC: Filters packets based on specific MPLS labels and VLAN tags using both predefined constants and negative indices.
Action Definitions:
- HandleVLANTraffic: Applies the VLAN_TRAFFIC filter, logs the detection, distributes traffic based on Hash5Tuple, and slices the packet payload.
- DistributeWithHash3Tuple: Applies another filter, logs the distribution action, and distributes traffic based on Hash3TupleGTPv1v2Sorted.

Best Practices

Adhering to best practices ensures that your JNPL scripts remain efficient, readable, and maintainable. Here are some recommendations tailored to the enhanced syntax and data types:

1. Modular Script Design

Organize your JNPL scripts into modular sections, each handling specific aspects of packet processing. This enhances readability and facilitates easier debugging and updates.

Example Structure:

// HashMode Definitions
define HashModes {
    define Hash5Tuple HashMode { ... }
    define Hash3TupleGTPv1v2Sorted HashMode { ... }
    define RoundRobin HashMode { ... }
    // Additional HashModes
}

// Protocol Definitions
protocol {
    define IP protocol { ... }
    define TRANSPORT protocol { ... }
    define APPLICATION protocol { ... }
    // Additional Protocols
}

// Filter Definitions
define Filters {
    define VLAN_TRAFFIC filter { ... }
    define MPLS_SEQUENCE_FILTER filter { ... }
    define VLAN_SEQUENCE_FILTER filter { ... }
    define InnerMPLSLabelFilter filter { ... }
    // Additional Filters
}

// Action Definitions
define Actions {
    action HandleVLANTraffic { ... }
    action HandleMPLSSequence { ... }
    action HandleVLANSequence { ... }
    action HandleInnerMPLSLabel { ... }
    action HandleDynamicMPLSLabel { ... }
    // Additional Actions
}

2. Consistent Naming Conventions

Use clear and consistent naming conventions for filters, actions, and hash modes to make scripts self-explanatory.

Examples:

Filters:
- VLAN_TRAFFIC
- MPLS_SEQUENCE_FILTER
- VLAN_SEQUENCE_FILTER
- InnerMPLSLabelFilter
Actions:
- HandleVLANTraffic
- HandleMPLSSequence
- HandleVLANSequence
- HandleInnerMPLSLabel
- HandleDynamicMPLSLabel
HashModes:
- Hash5Tuple
- Hash3TupleGTPv1v2Sorted
- RoundRobin

3. Comprehensive Commenting

Include comments to explain complex logic or important decisions within the scripts. This aids future maintenance and helps other users understand the script's intent.

Example:

// Filter for VLAN traffic with specific MPLS labels and VLAN tags
define VLAN_TRAFFIC filter {
    Frame[4:2] == IPv4
    MPLS[TopLabel].Id == 100 AND MPLS[BottomLabel].Label == 200
    VLAN[TopLabel].Id == 100 AND VLAN[BottomLabel].Id == 200 AND VLAN.Count >= 2 AND VLAN.Payload == 3
    Layer3.Type in [IPv4, IPv6]
    Layer4.Type == TCP
    Port == 4
}

4. Priority Management

Carefully assign priority levels to ensure that critical rules are processed before less important ones. Avoid overlapping filters with conflicting actions unless intentional.

Example:

// Highest priority: Drop traffic from blacklisted IPs
define DropBlacklisted filter {
    IP.Src in blacklisted_ips
}

define ActionDropBlacklisted action {
    log "Blocked traffic from blacklisted IP"
    drop
}

action DropBlacklisted {
    priority = 0
}

// High priority: Handle VLAN traffic
define HandleVLANTraffic filter {
    VLAN_TRAFFIC == true
}

define ActionHandleVLANTraffic action {
    log "SYN packet from 192.168.1.1 detected"
    distribute = (0..3) based on Hash5Tuple
    slice = 12:64
}

action HandleVLANTraffic {
    priority = 10
}

// Default handling with lowest priority
define DefaultHandling filter {
    true
}

define ActionDefaultHandling action {
    log "Default handling for all other traffic"
    assign to_module "default_processor"
}

action DefaultHandling {
    priority = 64
}

5. Error Handling and Validation

Ensure that your scripts handle potential errors gracefully and validate conditions effectively.

Example:

action HandleVLANTraffic {
    filter VLAN_TRAFFIC == true

    if (Packet.Payload.length < 64) {
        log "Payload too short, dropping packet"
        drop
    } else {
        log "SYN packet from 192.168.1.1 detected"
        distribute = (0..3) based on Hash5Tuple
        slice = 12:64
    }
}

6. Utilize Reusable Components

Define reusable filters, actions, and hash modes to avoid redundancy and promote consistency across scripts.

Example:

define CommonFilters {
    define DropBlacklisted filter { ... }
    define HighPriorityTraffic filter { ... }
    define MPLS_SEQUENCE_FILTER filter { ... }
    // Additional Common Filters
}

define CommonActions {
    define ActionDropBlacklisted action { ... }
    define ActionHandleHighPriority action { ... }
    define ActionHandleMPLSSequence action { ... }
    // Additional Common Actions
}

define CommonHashModes {
    define Hash5Tuple HashMode { ... }
    define RoundRobin HashMode { ... }
    // Additional Common HashModes
}

Tooling Support

To maximize the usability of JNPL, especially with the enhanced array accessors and negative indices, consider developing or integrating the following tools:

1. Syntax Highlighting for Code Editors

Creating syntax highlighting for JNPL in popular code editors like Visual Studio Code or Sublime Text can significantly enhance the user experience.

Example for Visual Studio Code

Define a TextMate Grammar:
- Create a jnpl.tmLanguage.json file outlining the syntax rules for JNPL.
- Include patterns for define, protocol, HashMode, filters, actions, comments, array accessors, and negative indices.

Sample jnpl.tmLanguage.json:

{
    "name": "JNPL",
    "fileTypes": ["jnpl"],
    "patterns": [
        {
            "name": "keyword.control.define.jnpl",
            "match": "\\bdefine\\b"
        },
        {
            "name": "entity.name.function.protocol.jnpl",
            "match": "\\bprotocol\\b"
        },
        {
            "name": "entity.name.function.hashmode.jnpl",
            "match": "\\bHashMode\\b"
        },
        {
            "name": "keyword.operator.assignment.jnpl",
            "match": ":"
        },
        {
            "name": "punctuation.definition.array-access.jnpl",
            "match": "\\[[-]?\\w+\\]"
        },
        {
            "name": "string.quoted.double.jnpl",
            "begin": "\"",
            "end": "\""
        },
        {
            "name": "comment.line.double-slash.jnpl",
            "begin": "//",
            "end": "$"
        },
        {
            "name": "constant.numeric.hex.jnpl",
            "match": "\\b0x[0-9A-Fa-f]+\\b"
        },
        {
            "name": "constant.numeric.jnpl",
            "match": "\\b\\d+\\b"
        },
        {
            "name": "entity.name.type.protocol.jnpl",
            "match": "\\bprotocol\\b"
        },
        {
            "name": "keyword.other.filter.jnpl",
            "match": "\\bfilter\\b"
        },
        {
            "name": "keyword.other.action.jnpl",
            "match": "\\baction\\b"
        },
        {
            "name": "keyword.control.condition.jnpl",
            "match": "\\bcondition:\\b"
        },
        {
            "name": "keyword.control.fields.jnpl",
            "match": "\\bfields:\\b"
        },
        {
            "name": "variable.other.constant.jnpl",
            "match": "\\b[TopLabel|BottomLabel]\\b"
        },
        {
            "name": "punctuation.definition.field.jnpl",
            "match": "\\."
        }
    ],
    "scopeName": "source.jnpl"
}

Package the Extension:
- Bundle the grammar file within a VS Code extension.
- Add necessary configuration files like package.json.
- Publish the extension to the VS Code Marketplace.
Usage:
- Users can install the extension and select JNPL as the language mode to enable syntax highlighting.

2. Linters and Formatters

Develop linters to validate JNPL scripts against the defined grammar and best practices, and formatters to ensure consistent code style.

Features:

Syntax Validation:
- Ensure all define/protocol, HashMode, filters, and actions adhere to the grammar.
- Validate correct usage of array accessors and negative indices.
Best Practices Enforcement:
- Check for consistent naming conventions.
- Ensure proper priority assignments.
- Enforce modular script structures.
Automatic Formatting:
- Align key-value pairs.
- Standardize indentation (e.g., 4 spaces per level).
- Ensure consistent casing for keywords and identifiers.

Example Implementation:

Linting Rules:
- Unique Definitions: Ensure each HashMode and protocol is uniquely defined.
- Required Fields: Verify that mandatory fields (e.g., Priority, Algorithm in HashMode) are present.
- Field Assignments: Check that field assignments follow the correct format (e.g., SrcPort = 0:2).
Formatting Tool:
- Implement a formatter that parses JNPL scripts and outputs them with standardized formatting.

Tools and Technologies:

ESLint-like Tool: Develop a custom linter using Node.js, leveraging AST (Abstract Syntax Tree) parsing libraries like Esprima or ANTLR.
Prettier Integration: Adapt Prettier to format JNPL scripts by defining appropriate rules.

3. Documentation Generators

Automate the creation of comprehensive documentation based on JNPL scripts, including:

API Documentation:
- Detailed descriptions of available commands, protocols, filters, actions, and hash modes.
Examples and Tutorials:
- Step-by-step guides demonstrating various use cases.
Reference Manuals:
- Exhaustive listings of all language constructs and their specifications.

Tools:

Doxygen: Adapt Doxygen or similar tools to parse JNPL scripts and generate HTML or PDF documentation.
Custom Scripts: Develop custom scripts to extract documentation comments and organize them into structured formats.

Example:

Doxygen Configuration:
- Define custom patterns to recognize JNPL-specific syntax.
- Annotate scripts with documentation comments using a consistent style (e.g., // @description).

Community and Contributions

Building a supportive community around JNPL can accelerate its adoption and improvement. Here are some strategies to foster community engagement:

1. Open-Source Repository

Host JNPL on a platform like GitHub to facilitate collaboration, issue tracking, and contributions.

Steps:

Create a Repository:
- Initialize a GitHub repository named JNPL or similar.
- Include a README.md with an overview, installation instructions, and basic usage examples.
Organize the Repository:
- /docs: Comprehensive documentation.
- /examples: Sample JNPL scripts demonstrating various features.
- /grammar: Formal grammar specifications and tooling scripts.
- /tools: Scripts for linting, formatting, and other utilities.
License and Contribution Guidelines:
- Choose an appropriate open-source license (e.g., MIT, Apache 2.0).
- Provide clear CONTRIBUTING.md guidelines to encourage and streamline community contributions.

2. Forums and Discussion Boards

Establish platforms for users to ask questions, share scripts, and discuss enhancements.

Options:

GitHub Discussions: Utilize GitHub’s built-in discussions feature for Q&A and community engagement.
Dedicated Forum: Create a forum using platforms like Discourse or Reddit.
Chat Channels: Set up real-time communication channels on Slack, Discord, or IRC.

3. Tutorials and Webinars

Host tutorials, webinars, and workshops to educate users about JNPL’s capabilities and best practices.

Content Ideas:

Introduction to JNPL: Basic concepts and getting started.
Advanced Filtering and Actions: Deep dives into complex use cases.
HashMode Customization: Tutorials on defining and utilizing custom hash modes.
Performance Optimization: Strategies for writing efficient JNPL scripts.

Testing and Validation

Implement comprehensive testing strategies to ensure the reliability and performance of JNPL scripts.

1. Unit Testing

Develop unit tests for individual components like filters, actions, and hash modes to ensure they function as intended.

Example:

// Test Case: Verify that VLAN_TRAFFIC filter correctly identifies matching packets
test VLAN_TRAFFIC_Filter {
    input_packet = {
        Frame[4:2] = IPv4
        MPLS[TopLabel].Id = 100
        MPLS[BottomLabel].Label = 200
        VLAN[TopLabel].Id = 100
        VLAN[BottomLabel].Id = 200
        VLAN.Count = 2
        VLAN.Payload = 3
        Layer3.Type = IPv4
        Layer4.Type = TCP
        Port = 4
    }

    expected_result = true

    assert filter(VLAN_TRAFFIC, input_packet) == expected_result
}

2. Integration Testing

Ensure that different parts of the script work seamlessly together, such as hash modes influencing distribution correctly.

Example:

// Integration Test: Ensure that packets are distributed based on Hash5Tuple
test DistributeBasedOnHash5Tuple {
    input_packet = {
        Frame[4:2] = IPv4
        MPLS[TopLabel].Id = 100
        MPLS[BottomLabel].Label = 200
        VLAN[TopLabel].Id = 100
        VLAN[BottomLabel].Id = 200
        VLAN.Count = 2
        VLAN.Payload = 3
        Layer3.Type = IPv4
        Layer4.Type = TCP
        Port = 4
    }

    action_result = execute_action(HandleVLANTraffic, input_packet)

    assert action_result.distribute_buffers == [0, 1, 2, 3]
    assert action_result.hash_value % 4 == 0 // Example condition
}

3. Performance Testing

Benchmark the performance of JNPL scripts, especially in high-throughput environments, to identify and address bottlenecks.

Tools:

Benchmark Scripts: Create scripts that simulate high volumes of packet processing.
Profiling Tools: Utilize profiling tools to measure execution time and resource usage.

Example:

# Run performance benchmark
./jnpl_processor --script test_script.jnpl --input high_volume_packets.pcap

Final Recommendations

Iterative Development:
- Continuously refine the JNPL syntax and features based on user feedback and evolving requirements.
Comprehensive Documentation:
- Maintain up-to-date and detailed documentation, covering all aspects of JNPL, including the corrected MPLS field access, array accessors, and negative indices.
Tooling Support:
- Prioritize the development of essential tools like syntax highlighters, linters, and formatters to enhance the user experience.
Community Engagement:
- Foster an active and supportive community to drive adoption, gather feedback, and encourage contributions.
Performance Optimization:
- Regularly profile and optimize the JNPL interpreter or compiler to ensure efficient packet processing, especially under heavy loads.
Security Considerations:
- Implement robust input validation and sandboxing mechanisms to prevent malicious scripts from compromising the system.
Extensibility:
- Design JNPL to be easily extensible, allowing for the addition of new protocols, actions, and hash modes without disrupting existing scripts.

Conclusion

By defining constants for array indices, enhancing data types, and refining the syntax to support multiple MPLS labels and VLAN tags with array accessors and negative indices, your JNet Packet Language (JNPL) scripts become more organized, readable, and maintainable. These refinements not only align with best practices but also ensure that your scripts function accurately in complex networking scenarios.

Next Steps

Implement the Corrected Syntax: Update your existing JNPL scripts with the corrected MPLS field access and ensure consistency across all protocol blocks.
Develop and Enhance Tooling: Continue developing syntax highlighting, linters, and formatters to support the refined syntax.
Expand and Update Documentation: Reflect the corrections and new data types in your comprehensive documentation to guide users effectively.
Engage and Grow the Community: Share the updated syntax and best practices with your user base to gather feedback and encourage collaborative improvements.

If you need further assistance with specific aspects of JNPL development, such as detailed grammar specifications, parser implementation, additional syntax examples, or tooling support, feel free to reach out! We're here to help you make JNPL as robust and user-friendly as possible.

Happy Networking with JNPL! 🚀

1.2.3 JNPL Syntax

JNet Packet Language (JNPL) Wiki

Table of Contents

Introduction

Key Features

Data Types

1. Byte Stream

2. Offset

3. Length

4. Range

5. Set

Syntax and Protocol Definitions

1. Implicit Type Definitions

2. Dot Notation for Field Access

3. Array Accessors with Constants and Negative Indices

4. Protocol Block Structure

Grammar Specification

Revised EBNF for JNPL

Key Enhancements

Example Scripts

Comprehensive JNPL Script

Explanation of the Example Script

Best Practices

1. Modular Script Design

2. Consistent Naming Conventions

3. Comprehensive Commenting

4. Priority Management

5. Error Handling and Validation

6. Utilize Reusable Components

Tooling Support

1. Syntax Highlighting for Code Editors

Example for Visual Studio Code

2. Linters and Formatters

3. Documentation Generators

Community and Contributions

1. Open-Source Repository

2. Forums and Discussion Boards

3. Tutorials and Webinars

Testing and Validation

1. Unit Testing

2. Integration Testing

3. Performance Testing

Final Recommendations

Conclusion

Next Steps

Clone this wiki locally