Language Server for OASIS TOSCA Version 2

This project was done in the context of Google Summer of Code 2024.

Project Information

Field	Details
Student	Omar Awad
Organization	Eclipse Foundation
Primary repository	org.eclipse.winery.lsp
Project name	TOSCA LSP Server
Project mentor	Dr. Oliver Kopp
Project page	Google Summer of Code 2024 Project Page
TOSCA Version 2.0	TOSCA Version 2.0 Committee Specification Draft

Project Summary

This project is an enhancement for Eclipse Winery. Eclipse Winery is a web-based environment for modeling OASIS TOSCA topologies. Currently, Winery focuses on providing a graphical editing environment for application topologies. It also covers many research prototype implementations.

This project implements a Language Server Protocol (LSP) provider for OASIS TOSCA YAML files. This make Eclipse Winery also a component for more text-based people and would lays a groundwork for integrating with other research. As a result, it provides users with assistance in editing TOSCA YAML files, making the creation and editing process more efficient and less error-prone.

Background

Applications today are often made up of multiple components, which may be distributed across various microservices. OASIS TOSCA (Topology and Orchestration Specification for Cloud Applications) is a standard designed to describe and manage these topologies. The core TOSCA specification defines a language for describing service components and their relationships using a service topology. It also includes lifecycle management procedures that enable the orchestration of services—covering creation, modification, and scaling—throughout the complete service lifecycle (e.g., deployment, scaling, patching, and monitoring). Currently, crafting TOSCA YAML files manually is complex and prone to errors due to the lack of tooling support. This project aimed to develop a Language Server for TOSCA v2 that integrates with Visual Studio Code.

Outcome

The outcomes of the project include:

1. LSP server supports the latest OASIS TOSCA 2.0 standard.
2. Awareness of the newly introduced types and definitions and makes them available in the service template.
3. Importing from multiple files TOSCA files within a repository or directory.
4. Context-dependent auto-completion for the TOSCA keywords and types.
5. Validation for the TOSCA types: artifact type, capability type, node type, and relationship type.
6. Validation for the definitions: imports definition, property definition, requirements definition, schema definition, and capability definition.
7. Validation for the templates: service template and node templates.
8. Enhanced key identification mechanism for the TOSCA files by prefixing keys with their parent elements and list indices, providing better clarity and traceability in nested YAML structures.
9. Demonstrating the functionality of the LSP server using compatible Visual Studio Code.

LSP Features

Context dependent auto-completion for TOSCA keywords.

Context dependent auto-completion for the types keyword value.

Node Templates

Capability Definitions

Context dependent auto-completion for the drived_from keyword value

Aritfact Type

Capability Type

Node Type

Relationship Type

YAML syntax validation with error reporting

Improved parsing of imports definitions for nested TOSCA files.

Support for multi-file TOSCA projects

The LSP is aware of the newly introduced types and definitions

Validation with error reporting for service, and node templates

Node Templates

Service Template

Validation with error reporting for schema, requirement, property, and capability definitions.

Schema Definition

Requirement Definition

Property Definition

Capability Definition

Validation with error reporting for node, relationship, capability, and artifact types.

Node Type

Relationship Type

Capability Type

Artifact Type

Validation with error reporting for the TOSCA boolean functions in the properties.

Future Work

• Add Go To definition feature to the LSP for the types and derived_from values.
• Complete the validation for the rest of the TOSCA file keynames.
• Add auto-completion for more contexts in tosca files such as auto-completing the requirement definition node and capability.
• Importing from other directories or repositories into the opened TOSCA file.

Benefits

• With enhanced YAML parsing, validation, and auto-completion, developers will be able to work more efficiently with complex TOSCA models.
• The validation mechanisms reduce the chances of errors due to incorrect file structures or values.
• The LSP makes it easier for developers to get real-time feedback while editing TOSCA YAML files in Visual Studio Code.

Key Learnings and Challenges

• Java Coding: I learned and deepened my knowledge of Java, which was essential for building the language server and handling various parsing tasks.

• LSP Protocol: Implementing the Language Server Protocol (LSP) was a new challenge, especially in handling communication between the client (VS Code) and the server. I learned how LSP works, including methods to provide language features such as autocomplete and error checking.

• Handling References in YAML Files: A significant challenge involved managing references to specific lines and sections in YAML files. I had to implement ways to correctly and uniquely identify and locate elements within the nested structure of TOSCA YAML files.

• Reading Specifications: The TOSCA 2.0 specification was completely new to me. I had to become familiar with reading to ensure correct implementation of TOSCA’s features within the language server. This skill was crucial to accurately translate spec requirements into functional code.

These areas, although challenging at times, have contributed greatly to my growth as a developer and my understanding of the TOSCA ecosystem.

Technologies and Tools

• Language: Java.
• Build System: Gradle.
• Editor: Visual Studio Code (for testing LSP features).
• TOSCA Specification: TOSCA Version 2.0.
• Java library: Eclipse LSP4j (for building the LSP server).
• Communication Protocol: Language Server Protocol (LSP) over stdio launcher.
• YAML Library: SnakeYAML (for parsing YAML files).

Statistics

Total commits	93
Changes	18078
Additions	18036
Deletions	42