{"id":21030566,"url":"https://github.com/workfloworchestrator/polynsi","last_synced_at":"2025-10-03T19:39:13.427Z","repository":{"id":73243869,"uuid":"235603889","full_name":"workfloworchestrator/PolyNSI","owner":"workfloworchestrator","description":"A SOAP to gRPC translating proxy server for the NSI protocol.","archived":false,"fork":false,"pushed_at":"2025-05-14T07:31:46.000Z","size":392,"stargazers_count":3,"open_issues_count":2,"forks_count":1,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-05-14T08:40:30.591Z","etag":null,"topics":["grpc","nsa","nsi-protocol","protocol-buffers","soap-client"],"latest_commit_sha":null,"homepage":null,"language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/workfloworchestrator.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2020-01-22T15:34:25.000Z","updated_at":"2025-04-22T11:51:32.000Z","dependencies_parsed_at":"2024-11-19T12:22:23.940Z","dependency_job_id":"f69d5135-4725-4e3c-9bf9-23b863fbcdeb","html_url":"https://github.com/workfloworchestrator/PolyNSI","commit_stats":null,"previous_names":[],"tags_count":6,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/workfloworchestrator%2FPolyNSI","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/workfloworchestrator%2FPolyNSI/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/workfloworchestrator%2FPolyNSI/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/workfloworchestrator%2FPolyNSI/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/workfloworchestrator","download_url":"https://codeload.github.com/workfloworchestrator/PolyNSI/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254330874,"owners_count":22053070,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["grpc","nsa","nsi-protocol","protocol-buffers","soap-client"],"created_at":"2024-11-19T12:19:15.440Z","updated_at":"2025-10-03T19:39:08.164Z","avatar_url":"https://github.com/workfloworchestrator.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"# PolyNSI\n\nA bidirectional SOAP to gRPC translating proxy server for the NSI protocol.\n\n# Introduction and Rationale\n\nNSI is a SOAP based protocol. [SOAP's specifications are unfortunately really\nvague and leave a lot of things open for\ninterpretation](https://python-zeep.readthedocs.io/en/master/index.html#quick-introduction)\n(see last paragraph of referenced section). Apart from being under specified,\nSOAP is rather complex. The result is that not many programming language\necosystems have full support for SOAP. In fact, full implementations (both\nserver and client) can only be found for:\n\n* Java\n* .NET (not even .NET Core)\n* C/C++\n\nSOAP client implementations can be found for many more programming language\necosystems. NSA implementations however, are both SOAP servers and clients.\n\nServices that implement the NSI protocol, are called Network Service Agents\n(NSAs). To allow convenient development of NSAs in other programming languages\necosystems than the above three, we have developed a proxy server in Java, that\ndoes nothing more than accepting SOAP requests, that it subsequently translates\nto requests using a more modern and widely used protocol and vice versa.\n\nAn obvious choice for the 'more modern protocol' would be REST/JSON.  Obvious,\nbecause that is all the hype these days and many people have considerable\nexperience with it. Downside is that endpoint and message specification using\nthe OpenAPI Specification is enormously verbose and a pain to read.\n\nAnother option would be to use gRPC with Protocol Buffers v3. Writing a\nspecification using Protocol Buffers is much more succinct and easy to read\nthan a verbose OpenAPI specification YAML file. Should we want to seek adoption\namong other National Research and Education Networks (NRENs) for an alternative\nNSI interface, readability will be an important factor. \n\nAnother benefit of gRPC is that it is a \n[Cloud Native Computing Foundation (CNCF)](https://www.cncf.io/) \nproject just like Kubernetes is. There is some overlap between the \n[Open Grid Forum](https://www.ogf.org/ogf/doku.php), where NSI originated, and\nCNCF. Sticking to similar technologies might invite contributions from people \nalready familiar in that space (easy transfer of skill sets)\n\nHence the choice for gRPC to translate NSI's native SOAP requests and responses\nto and from. With the ability to develop NSAs more conveniently in a wider\narray of programming languages we hope to improve the uptake of the NSI\nprotocol. And possibly direct gRPC to gRPC NSA interaction without PolyNSI's\nintervention.\n\n## A note on gRPC and its relation to Protocol Buffers\n\ngRPC is an extension of Protocol Buffers. Messages are still defined using\nProtocol Buffers v3. The service definitions (=remote procedures) though,\nextend the Protocol Buffers syntax. This means that the Protocol Buffers\ncompiler `protoc` cannot compile all the `.proto` files used for gRPC. The\ncompiler needs a plugin to do so. \n\n# Quick Start\n\n* [install (Open)JDK 11](https://openjdk.java.net/)\n* [install Apache Maven](http://maven.apache.org/install.html)\n* mvn clean generate-sources\n* mvn test\n* mvn spring-boot:run\n* point your browser at: http://localhost:8080/soap\n\n# Installation\n\nNormally the Quick Start instructions should be all that's required to get\nPolyNSI installed and running with a default configuration. Maven will find\neverything it needs and installs it into its local repository. Thus making it\navailable to PolyNSI. This includes binary dependencies such as the Protocol\nBuffers compiler with its gRPC plugin. However, for some less common, but\notherwise equally relevant OSes in the networkin space, such as FreeBSD, a bit\nmore work is required. See the section \n[Advanced Installation](#Advanced-Installation) for more details.  \n\n# Configuration\n\nAll PolyNSI configuration is done by properties. As PolyNSI is a Spring Boot\napplication it follows Springs Boot's conventions for obtaining \n[those properties from files](https://docs.spring.io/spring-boot/docs/2.3.2.RELEASE/reference/html/spring-boot-features.html#boot-features-external-config-application-property-files).  \n\nPolyNSI's default configuration resides in\n`src/main/resources/application.properties` where the properiets are documented\nas well. Things that you almost certainly will have to configure are the\nSOAP server side of PolyNSI including the SSL configuration,\nand the gRPC side of PolyNSI that faces the gRPC based NSA:\n\n~~~\n        cxf.path\n        soap.server.*  +---------+  grp.client.*            +-------+\n        server.*       |         |-------------------------\u003e| gRPC  |\n        --------------\u003e| PolyNSI |                          | based |\n                       |         |\u003c-------------------------| NSA   |\n                       +---------+  grpc.server.*           +-------+\n~~~\n\nA typical `application.properties` contains the following configuration options:\n\n    #\n    # PolyNSI application properties\n    #\n    debug=false\n    logging.config=file:/usr/local/etc/polynsi/logback-spring.xml\n    #\n    # SOAP provider endpoint configuration\n    #\n    cxf.path=/soap\n    soap.server.connection_provider.path=/connection/provider\n    soap.server.connection_requester.path=/connection/requester\n    #\n    # SOAP provider SSL configuration\n    #\n    server.port=8443\n    server.ssl.enabled=true\n    server.ssl.client-auth=need\n    server.ssl.key-store=/usr/local/polynsi/polynsi-keystore.jks\n    server.ssl.key-store-type=jks\n    server.ssl.key-store-password=secret\n    server.ssl.trust-store=/usr/local/polynsi/polynsi-truststore.jks\n    server.ssl.trust-store-type=jks\n    server.ssl.trust-store-password=secret\n    #\n    # gRPC server configuration\n    #\n    grpc.server.port=9090\n    #\n    # gRPC client configuration\n    #\n    grpc.client.connection_provider.address=static://localhost:50051\n    grpc.client.connection_provider.negotiationType=PLAINTEXT\n\nSee also:\n* [Application Property Files](https://docs.spring.io/spring-boot/docs/2.3.2.RELEASE/reference/html/spring-boot-features.html#boot-features-external-config-application-property-files)\n* [Common (Spring Boot) Application Properties](https://docs.spring.io/spring-boot/docs/2.3.2.RELEASE/reference/html/appendix-application-properties.html#common-application-properties)\n\n# Advanced Installation\n\nAs detailed in the section [Installation](#Installation) some OSes, such as\nFreeBSD, require a bit more work to install PolyNSI on. The reason for this is\nthat the Protocol Buffers and gRPC projects do not provide precompiled versions\nof their compiler and plugin for them. Hence we need to compile these\nourselves. In some cases the package manager of the OS in question might help us\nwith that. That happens to be the case with FreeBSD as we will shortly see. \n\n\n## Building the gRPC protoc plugin on FreeBSD\n\nFirst install the `protobuf` package:\n\n    $ sudo pkg protobuf\n    \nThis not only installs the `protoc` compiler, but also all the relevant\nheader files needed, to build the gRPC compiler plugin. For Maven to use the\n`protoc` compiler we need to tell it where to find it:\n\n    $ mvn install:install-file \\\n        -DgroupId=com.google.protobuf \\\n        -DartifactId=protoc \\\n        -Dversion=3.12.2 \\\n        -Dclassifier=freebsd-x86_64 \\\n        -Dpackaging=exe \\\n        -Dfile=/usr/local/bin/protoc\n\nNext checkout the 1.29 branch of the `grpc-java` project. This project\ncontains a `protoc` plugin that generates Java files.\n\n    $ git clone -b v1.29.0 https://github.com/grpc/grpc-java\n    \nOn FreeBSD, third party libraries and headers files are located in `/usr\n/local/lib` and `/urs/local/include` by default. The `grpc-java` build\nsystem is unaware of those locations. Hence, we need to tell it about them:\n\n    $ export CXXFLAGS=\"-I/usr/local/include\" LDFLAGS=\"-L/usr/local/lib\"\n    \nYes, the `protoc` compiler is a C++ application and so is the gRPC\nplugin for Java!\n \nWe also need to tell the `grpc-java` build system where to find the\n`protoc` compiler. Furthermore, we are not interested in building things\nfor Android. So we create a file `grpc-java/gradle.properties` and add\nthe following lines to it:\n \n    skipAndroid=true\n    protoc=/usr/local/bin/protoc\n    \nBefore we build the plugin, we need to do one last thing; patch a\nBash script that sanity checks the build artifact. Currently, it only\nrecognizes artifacts (the plugin) built on Linux, MacOS and\nWindows. The patch teaches it about FreeBSD:\n\n    $ cd grpc-java/compiler\n    $ git apply \u003c...\u003e/polynsi/grpc-java-compiler.patch\n \nBuilding the plugin should now be a simple matter of (while still being\nin the directory `grpc-java/compile`):\n\n    $ ../gradlew clean java_pluginExecutable test publishToMavenLocal\n\nTo test whether the plugin now actually resides in your local Maven \nrepository, execute:\n\n    $ ls -l ~/.m2/repository/io/grpc/protoc-gen-grpc-java/1.29.0/\n    \nThat directory should have a file called.\n`protoc-gen-grpc-java-1.29.0-freebsd-x86_64.exe`\n\n## Building protobuf-java jars on FreeBSD\n\nGenerally, the required `protobuf-java` jars are available from the Maven Central\nRepository and will be downloaded by Maven automatically. However sometimes we\nwant to build them from source if we need a specific version that's not yet\navailable from the Maven Central Repository. \n\nBuilding the `protobuf-java` jars requires the `protoc` compiler, that we\nalready have installed, but in a different location from where the build\nconfiguration expects it. Contrary to `grpc-java` that uses the Gradle build\nsystem, `protobuf-java` uses Maven. As such, specifying the location of the\n`protoc` compiler is a little different. Even more so as protobuf-java uses an\naggregate POM. With an aggregrate POM, properties specified on the command line\nusing the `-D` parameter, are not passed on to submodules (POMs). That makes it\nless than trivial to set a value for the `protoc` property if it needs to be\nshared by all submodules. However, with a `settings.xml` file in the `~/.m2`\ndirectory we will be able to set property values that will be picked up by any\nPOM, whether it is a submodule or not.\n\nSo create a file `~/.m2/settings.xml` with the following contents:\n\n    \u003csettings xmlns=\"http://maven.apache.org/SETTINGS/1.0.0\"\n              xmlns:xsi=\"http://www.w3.org/2001/XMLSchema-instance\"\n              xsi:schemaLocation=\"http://maven.apache.org/SETTINGS/1.0.0\n                              https://maven.apache.org/xsd/settings-1.0.0.xsd\"\u003e\n        \u003cprofiles\u003e\n            \u003cprofile\u003e\n                \u003cid\u003efreebsd\u003c/id\u003e\n                \u003cactivation\u003e\n                    \u003cactiveByDefault\u003etrue\u003c/activeByDefault\u003e\n                \u003c/activation\u003e\n                \u003cproperties\u003e\n                    \u003cprotoc\u003e/usr/local/bin/protoc\u003c/protoc\u003e\n                \u003c/properties\u003e\n            \u003c/profile\u003e\n        \u003c/profiles\u003e\n    \u003c/settings\u003e\n\nWith that out of the way we now need to clone the `protobuf` repository:\n\n    $ git clone git@github.com:protocolbuffers/protobuf.git\n\nThe version of the `protobuf-java` jars we want to build, need to match the\nversion of the protoc compiler:\n\n    $ protoc --version\n    libprotoc 3.12.2\n\nThis shows that we need to checkout the v3.12.2 release:\n\n    $ cd protobuf\n    $ git checkout v3.12.2\n    \nAnd, finally, build the `protobuf-java` jars:\n\n    $ cd java\n    $ mvn install\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fworkfloworchestrator%2Fpolynsi","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fworkfloworchestrator%2Fpolynsi","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fworkfloworchestrator%2Fpolynsi/lists"}