WebService Configuration

The web service plugin can handle multiple web server instances. Each of them has its own context and runs as an independent task.

The web service is configured in the settings.json and contains all settings of the web service plugin.

Structure of the Xml is:

• HumanOS.PeSeL.WebService.TWebServicePlugin
  • ServiceInstance
    • Modules
      • Functions
  • ProxyInstance
  • LocatorInstance

Web Service Instances

Each web service instance has its own configuration. There exist two variants: HTTP and HTTPS.

HTTP Configuration

Attribute	Description	Data Type
Id	Instance Id	System.Guid

Parameter	Description	Data Type
Port	Listening port of the service	System.Int32

HTTPS Configuration

The X509 certificate is configured in the service instance settings.

Attribute	Description	Data Type
Id	Instance Id	System.Guid

Parameter	Description	Data Type
Port	Listening port of the service	System.Int32
X509CertificateFile	File name of the X509 certificate	System.String
X509CertificatePassword	Optional password	System.String

Whitelisting RESTful Calls

Each service instance can optionally declare a whitelist of accepted RESTful calls.

Attribute	Description	Data Type
method	HTTP method (GET, DELETE, PATCH, POST)	System.String

Note: The URL is case sensitive!

Example

"AcceptedCalls": [
        "GET /nodes"
      ]

Modules

A module (specifically the module name) defines a custom endpoint (http://<hostname>/<module name>). A module must define one or more functions. Each of these functions must be scripted.

Example:

  "Modules": [
    {
      "Name": "TestModule",
      "Functions": [
        {
          "Name": "TestFunction",
          "Methods": [
            "GET",
            "POST"
          ],
          "Script": "TestScript.cs"
        },
        {
          "Name": "TestFunction2",
          "Methods": [
            "GET",
            "PATCH",
            "POST"
          ],
          "Script": "TestScript.cs"
        },
        {
          "Name": "TestFunction3",
          "Methods": [
            "GET"
          ],
          "Script": "xxx"
        }
      ]
    },
    {
      "Name": "TestModule2",
      "Functions": [
        {
          "Name": "TestFunction",
          "Methods": [
            "DELETE"
          ],
          "Script": "TestScript.cs"
        }
      ]
    }
  ]

The number of modules is not limited.

Functions

A function always belongs to a module. Each function must define a Sub path (function name, http://<hostname>/<module name>/<function name>), supported HTTP Methods and the belonging script. See Modules for an example. Further sub paths can be implemented on scripting level.

The script is then provided as follows and must be placed in the <Projectpath>\Config\HumanOS.PeSeL.WebService folder:

using HumanOS.Kernel;
using System;
using System.Collections.Generic;
using HumanOS.PeSeL.WebService.Script;
using HumanOS.Kernel.PeSeL.Script;
using HumanOS.Kernel.Communication.Http;
using Griffin.Net.Protocols.Http;
using Newtonsoft.Json.Linq;

/// <summary>
/// Script defining the payload
/// </summary>
public class AnsibleInventory : TAbstractWebScriptObject
{
  /// <summary>
  /// Handles a web GET request
  /// </summary>
  /// <param name="Kernel"></param>
  /// <param name="Context"></param>
  /// <param name="dicParams"></param>
  /// <param name="lstPath"></param>
  /// <param name="reContentType"></param>
  /// <returns></returns>
  public override string handleGet(IKernelAccess Kernel,
                                       TPayloadProcessingContext Context,
                                       List<string> lstPath,
                                       Dictionary<string, string> dicParams,
                                       ref EContentType reContentType)
  {
    return new JObject(new JProperty("Hallo", "Test!")).ToString();
  }

  /// <summary>
  /// Handles a web DELETE request
  /// </summary>
  /// <param name="Kernel"></param>
  /// <param name="Context"></param>
  /// <param name="reContentType"></param>
  /// <param name="lstPath"></param>
  /// <param name="dicParams"></param>
  /// <param name="strData"></param>
  /// <returns></returns>
  public override string handleDelete(IKernelAccess Kernel,
                                       TPayloadProcessingContext Context,
                                       List<string> lstPath,
                                       Dictionary<string, string> dicParams,
                                       ref EContentType reContentType,
                                       string strData)
  {
    throw new NotImplementedException();
  }

  /// <summary>
  /// Handles a web PATCH request
  /// </summary>
  /// <param name="Kernel"></param>
  /// <param name="Context"></param>
  /// <param name="strData"></param>
  /// <param name="dicParams"></param>
  /// <param name="lstPath"></param>
  /// <param name="reContentType"></param>
  /// <returns></returns>
  public override string handlePatch(IKernelAccess Kernel,
                                       TPayloadProcessingContext Context,
                                       List<string> lstPath,
                                       Dictionary<string, string> dicParams,
                                       ref EContentType reContentType,
                                       string strData)
  {
    throw new NotImplementedException();
  }

  /// <summary>
  /// Handles a web PATCH request
  /// </summary>
  /// <param name="Kernel"></param>
  /// <param name="Context"></param>
  /// <param name="reContentType"></param>
  /// <param name="lstPath"></param>
  /// <param name="dicParams"></param>
  /// <param name="strData"></param>
  /// <param name="Response"></param>
  /// <returns></returns>
  public override string handlePost(IKernelAccess Kernel,
                                       TPayloadProcessingContext Context,
                                       List<string> lstPath,
                                       Dictionary<string, string> dicParams,
                                       ref EContentType reContentType,
                                       string strData,
                                       IHttpResponse Response)
  {
    throw new NotImplementedException();
  }
}

The Kernel object allows the script to have full access to the HumanOS® NodeSpace.

Configuration Example

{
  "Disable": false,
  "Services": [
    {
      "Id": "FE4B8CFB-82BD-4CD3-BDDA-483572E009E7",
      "Port": 8081
    },
    {
      "Id": "6D75B0C9-980C-4DB2-8D14-21E552DF3618",
      "Port": 44300,
      "X509CertificateFile": "$(AppConfig:CertificatePath)HumanOS.self.pfx",
      "X509CertificatePassword": ""
    },
    {
      "Id": "5EA04A73-8CDA-4920-8B72-A9A6B19E0552",
      "Port": 8083,
      "Modules": [
        {
          "Name": "TestModule",
          "Functions": [
            {
              "Name": "TestFunction",
              "Methods": [
                "GET",
                "POST"
              ],
              "Script": "TestScript.cs"
            },
            {
              "Name": "TestFunction2",
              "Methods": [
                "GET",
                "PATCH",
                "POST"
              ],
              "Script": "TestScript.cs"
            },
            {
              "Name": "TestFunction3",
              "Methods": [
                "GET"
              ],
              "Script": "xxx"
            }
          ]
        },
        {
          "Name": "TestModule2",
          "Functions": [
            {
              "Name": "TestFunction",
              "Methods": [
                "DELETE"
              ],
              "Script": "TestScript.cs"
            }
          ]
        }
      ]
    }
  ],

  "Proxies": [
    {
      "Id": "88A4B675-3A09-4B59-8045-F302D9460DB9",
      "Port": 8082,
      "Target": "https://localhost:44300",
      "X509CertificateFile": "$(AppConfig:CertificatePath)HumanOS.self.pfx",
      "X509CertificatePassword": "",
      "AcceptedCalls": [
        "GET /nodes"
      ],
      "AcceptedCertificates": [
        {
          "Name": "HumanOS.self.pfx",
          "Hash": "3f9b4f7fb05709edf8f40e30d7b7592ee8b48129"
        }
      ]
    }
  ]
}

Web Proxy Instances

The web proxy is used to filter and relay the REST Calls to a web service instance (locally or remotely).

Attribute	Description	Data Type
Id	Proxy Id	System.Guid

Parameters are equal to the service instance configuration. Following parameter extend the configuration for web proxy:

Parameter	Description	Data Type
Target	Target URL	System.System
IgnoreCertificateErrors	Ignore certificate errors coming from the target server.	System.Boolean

Whitelisting Certificates

Optional, a list of trusted certificates can be given. This is necessary if the certificates cannot be validated.

Parameter	Description	Data Type
Hash	Hash-String of trusted certificate	System.String

Example:

  "AcceptedCertificates": [
    {
      "Name": "HumanOS.self.pfx",
      "Hash": "3f9b4f7fb05709edf8f40e30d7b7592ee8b48129"
    }
  ]

Configuration Example

The example shows a setting where a proxy on port 8082 listens to HTTPS calls and relays them to the https://localhost. The web proxy is configured as a filter, only passing the GET /nodes call.

"Proxies": [
    {
      "Id": "88A4B675-3A09-4B59-8045-F302D9460DB9",
      "Port": 8082,
      "Target": "https://localhost",
      "X509CertificateFile": "$(AppConfig:CertificatePath)HumanOS.self.pfx",
      "X509CertificatePassword": "",
      "AcceptedCalls": [
        "GET /nodes"
      ],
      "AcceptedCertificates": [
        {
          "Name": "HumanOS.self.pfx",
          "Hash": "3f9b4f7fb05709edf8f40e30d7b7592ee8b48129"
        }
      ]
    }
  ]