Core Concepts

Web Server

Introduction

The web server in kOS plays a critical role. Since all UI within kOS runs within a browser, the server is responsible for delivering application content as well as hosting endpoints that fetch application data.

In addition, the application model within kOS is based on microservices, which means that within Java, calls between applications rely on endpoints. Given the central role the web server plays in kOS, the server is custom-built to support a number of unique use cases that arise in embedded development.

Details

HTTP over websocket

The kOS UI toolkit provides a transport mechanism to interface with the server, and this uses a websocket instead of standard HTTP requests. Not only does this make connectivity error handling much easier, but also allows for interleaved requests and responses over a single connection. This transport also connects directly to the clustered networking stack, which allows requests to be routed to any node in the cluster (for more details, see Clustering).

Strict ordering of requests

When using HTTP, there is no way to guarantee that two requests that are sent back-to-back are processed in the same order as sent. A client may have more than one connection to the server, which means that requests could reach the server in a different order. Once on the server, the requests are typically dispatched to a thread pool, where it is possible that the threads are scheduled in a different order than when the requests arrived.

Consider a "start pour" command followed immediately by a "stop pour" command. If processed out of order, the stop will do nothing and the pour will run until the max pour limit is reached. Using the kOS transport with the kOS web server, it is possible to tag a request as being ordered. All ordered requests are guaranteed to be processed in the order in which they are sent.

Support for asynchronous results

Physical devices perform many long-running operations that do not align well with typical endpoints. For example, consider an endpoint that sanitizes a device, an operation that can take up to 45 minutes to complete. kOS provides abstractions to perform asynchronous work within Java (see Asynchronous Work section), and the web server extends this support to the client.

If an endpoint returns asynchronous work, the server automatically tracks the work and then periodically sends progress information over the originating websocket. This continues until the work completes. This allows the client to drive progress bars and determine the final state of the operation without any other work on behalf of the developer.

Optional responses

Not all endpoints return a meaningful response. In a typical web application, the response is required to ensure that the server received the request. However, when running over a websocket, the status of the underlying transport can be used to ensure that the server receives the request. Thus, the response is of no value and simply causes the client to needlessly block. When used in conjunction with the websocket transport, the server supports not returning a response to a request. This effectively allows endpoints to act as event listeners.

Endpoint version information

It is common for a typical web application to support multiple versions of an endpoint to provide backward compatibility. This is relatively easy for two reasons. First, typical web applications primarily operate on stored data which can be transformed into different formats as it is loaded from storage. Second, any impact on overall capacity can be mitigated by adding more servers in the cloud. However, when dealing with an embedded device, much of the data is actually the internal state of the hardware or live control data, not data at rest. This means that the format of the data is dictated by the needs of the hardware or control algorithm, and transforming this data to alternate forms may be impossible.

Embedded systems are also resource-constrained, and may not have the CPU or memory available to support backward-compatible formats. This can cause complexity when external systems need to process data from equipment that are running different versions of code. kOS helps solve this by pushing the problem off the device to the external systems, which typically have more capacity available to normalize the data. This is achieved by returning per-endpoint version information in every response.

More

Developing endpoints within kOS is very similar to using Spring controllers, and share many of the same annotations. For example, a class that contains endpoint methods can be annotated with @Controller, so it can be automatically processed by the server. Similarly, @PathVariable, @RequestBody, and @RequestParam exist to extract data from a request.

The web server is also able to serve content, but all content is served from a virtual filesystem (VFS) that exists within kOS. This allows content to be mapped into the VFS independent of the actual physical filesystem. The VFS in kOS is dynamically constructed from VFSSource objects. There are multiple implementations of VFSSource including:

  • KabVFSSource : Makes the contents of a KAB file visible via HTTP. This is the most common form of mounting content into the VFS since most content is packaged into KAB files for delivery to kOS.

  • FilesystemVFSSource : Makes the content started at the specified directory in the native filesystem visible via HTTP.

For more information about writing endpoints see TODO.

Summary

TODO

Previous
Next
On this page
Java Development
Seamlessly transition from Legacy+ systems to Freestyle microdosing and advanced distributed dispense systems.
UI Development
Using kOS SDKs, integrating Consumer and Non-consumer facing UIs becomes seamless, giving you less hassle and more time to create.
Video Library
Meet some of our development team, as they lead you through the tools, features, and tips and tricks of various kOS tools.
Resources
Familiarize yourself with kOS terminology, our reference materials, and explore additional resources that complement your kOS journey.
Copyright © 2024 TCCC. All rights reserved.