Skip to content

Latest commit

 

History

History
400 lines (266 loc) · 19.6 KB

VALSTAT.md

File metadata and controls

400 lines (266 loc) · 19.6 KB
Raw

valstat - response protocol

   
Document Number: DBJ0001
Date 2022-01-14
Audience
Author Dusan B. Jovanovic ( [email protected] )

Revision history

2021-01-01 R1: created 2021-01-14 R2: simplified

Table of Contents

1. Abstract

This is a proposal about logical, feasible, lightweight and effective protocol for handling the function response activity, decoupled from both platforms and languages.

This paper describes an function software protocol, not language specific implementations or platform specific solutions.

2. Motivation

Economy of software production is an ever more delicate balancing act. Because of its prominent costs, feasible integration is a common recurring theme in a software development. It is complex and difficult task to predict and solve in advance, integration problems in a feasible level of detail. Thus software integration contributes to the raising costs of software, on all levels of detail.

Software artifacts levels of integration, ordered by the scope, from wide to narrow:

scope level
wide universal
domain
system
application
component
narrow code

Calling a function, creating a response, returning a response and handling the response, is activity permeating all levels of software construction.

Feasibility of the integration requires a high level of simplicity and resilience. Integration resilience requires a common and simple guidances. VALSTAT is attempt to provide on of those guidances, in the format of a standard protocol.

3. The Protocol

By function "call" in here we mean the "call" in its most overarching definition. This protocol is applicable regardless of the function call/response category. Remote, Local, Synchronous, asynchronous, direct, message based, RPC, HTTP, or whatever.

A function call/response, software activity guided by a protocol is a paradigm shift.

"A paradigm is a standard, perspective, or set of ideas. A paradigm is a way of looking at something ... When you change paradigms, you're changing how you think about something..." vocabulary.com

3.1. Building Blocks

VALSTAT protocol central theme is a lightweight structure returned by "Responder" to the "Caller", as a consequence of a call.

  • CALLER is software entity calling the local or remote function or component.
  • RESPONDER is a software entity creating a VALSTAT structure to be returned to a CALLER
CALLER --> (function local/remote call) --> RESPONDER

CALLER <-- (return VALSTAT structure instance) <-- RESPONDER

Locality: CALLER and RESPONDER can reside inside the same or different, application or system domains. Local or remote to each other. On all levels of information system. CALLER and RESPONDER are locality independant.

Valstat function response logic is divided in two steps

As part of response handling activity, regardless of platform or language, the two steps logic is always present:

  1. step one -- Is something returned?
  2. step two -- Can I use it?

Conceptually valstat protocol is the "two steps" function return consuming:

  1. use the structure returned to determine the step two
    • not using the type system or actual values returned
  2. use the content returned
    • using the type system and values returned

That is a two step logic, that can be applied across many (if not all) software development platforms and run-time domains.

3.2. VALSTAT structure

VALSTAT structure is an record made of two fields:

  • VALSTAT record
    • VALUE
    • STATUS

Caveat emptor: names are not mandatory. You can call them anything you like as long as you preserve the meaning. I use these names because I think they mean what I want them to mean to the member of the target audience of this document.

3.3. Field

VALSTAT "field" is analogous to the database field. "field" is the name for an "single piece of information". In present days (circa 2022) field is often called an "key value pair".

In database theory "field" is: "a particular piece of data encapsulated within a class or object".

I am thinking of a field as the primary particle in the context of a computer sceince. As in other places field has states.

Key states of a field are:

  1. Existence: field always exists
  2. EMPTY : has no value
  3. OCCUPIED : has value

Field primary two states describe its Emptiness. : EMPTY or OCCUPIED

3.3.1. Field Emptiness

Field can be primarily in two "occupancy states" (authors term) . We will call them : "empty" and "occupied".

field two occupancy states

In software development terms field is an always present object potentially holding a value. It can be tested if it is "empty" , or occupied aka "holding a value".

3.4. VALSTAT State

Any Value natural states are describing its existence: EXIST or NON-EXISTENT

Combination of two fields primary states and value natural states is giving four possible states.

valstat record state decoding

Valstat Record states are named.

State Tag Value occupancy op Status occupancy
Info Has value AND Has value
OK Has value AND Empty
Error Empty AND Has value
Empty Empty AND Empty

VALSTAT state names (tags) are just that: tags. Not mandating but just indicating the behaviour.

Evaluating the returned VALSTAT structure instance we do not immediately inspect function returned values inside the fields.

In step one we inspect the relationship of two fields primary states. Empty and occupied.

Returned structure instance handling, step one is only about the relationship between two fields states of occupancy. Values and their types are not used and not relevant for the step one. That is important: ste one does not use any type system.

To reiterate: VALSTAT state decoding is the act of decoding the relationship between occupancy states of its two fields.

Following is synopsis of decoding one of the four possible VALSTAT states:

// (c) by [email protected]
// pseudo code
// step one: capturing one of four possible VALSTAT states

In step one types or values of the content returned are not used just the occupancy states

// empty AND empty
  if (   is_empty( value ) &&   is_empty( status )  { /* state: empty */ }

// empty AND occupied  
  if (   is_empty( value ) && ! is_empty( status )  { /* state: error   */ }

// occupied AND empty
  if ( ! is_empty( value ) &&   is_empty( status )  { /* state: ok */ }

// empty AND empty  
  if ( ! is_empty( value ) && ! is_empty( status )  { /* state: info*/ }

On the code level, that synopsis can be implemented, almost as it is, in many languages: C, JavaScript, Python, GO, Java, C# etc.

NOTE: in particular language binding of the VALSTAT we very often do not need separate is_empty() function implemented. Here is canonical C++ as an clarification.

// calling
auto [value, status] = valstat_returning_function ();

// step one: capturing the one
// of four possible states
// is_empty() not necessary
  if (   value &&   status )  { /* info */ }
  if (   value && ! status )  { /* ok   */ }
  if ( ! value &&   status )  { /* error*/ }
  if ( ! value && ! status )  { /* empty*/ }

VALSTAT Protocol return handling code is neatly divided in two steps. VALSTAT handling logic serves well for the arrival to cleaner idioms for complex call consumption code. Canonical example: handling od HTTP responses.

3.5. The VALSTAT Responder Behaviour

From the callable software entity, an VALSTAT Responder is "signalling back" by following the encapsulated application logic; and then creating and returning the appropriate VALSTAT structure.

Reminder. The VALSTAT structure pseudo code declaration.

record VALSTAT  
     field VALUE
     field STATUS

Function RESPONDER is creating the appropriate VALSTAT record. RESPONDER returning the valstat in a "OK" state:

// pseudo code of a OK valstat instance return
// creating occupied value field and empty status field 
return VALSTAT  
     VALUE = (value), STATUS = (EMPTY)

Both value and EMPTY are meaningful software entities, for their application language domain. NExt; RESPONDER signalling the "INFO" state:

// occupied value field and occupied status field 
return VALSTAT  
     VALUE = (value), STATUS = (information)

RESPONDER signalling the "ERROR" state

// empty value field and occupied status field 
return VALSTAT  
     VALUE = (EMPTY), STATUS = (information)

And finaly the use case of RESPONDER signalling the "EMPTY" valstat

// empty value field and empty status field 
return VALSTAT  
     VALUE = (EMPTY), STATUS = (EMPTY)
eof return

Valstat 'RESPONDER' is simply the implementation of a function, that when called returns the instance of a VALSTAT record.

4. The Logic

4.1. Why the "two"?

Context depends on the domain. As ever in the information systems, the meaning of the information is context specific.

VALSTAT is a protocol aiming for light and efficient information passing.

VALSTAT is not a messaging protocol. Contrast it to some protocol using (for example) XML (or JSON) documents for functions calling and function return values. That can be imagined but author is not aware of such a protocol. Probably being not simple, and thus not resilient. Resilience and complexity do not mix.

But anything between that and VALSTAT record of two fields, is not as light and not as efficient as VALSTAT structure.

And going bellow the two fields, degenerates back to the "single error value return" anti-pattern.

4.2. IT landscape matters

High utility of the VALSTAT protocol lies in it's deliberate simplicity. Mechanism simple but still capable in aiding and solving the software operational and interoperability issues. On all levels of construction.

Modern software architectures are clusters of inter-operating but separated components and sub-systems. After decades of somewhat chaotic growth, one thorny big software engineering issue, is solving universally applicable returns handling, across languages and components and even system barriers. And this is where VALSTAT as a protocol might help. (think JSON format for VALSTAT protocol implementation)

Universal adoption of the VALSTAT requires no changes in any of the software development languages. It just has to be universally adopted, used and architected with.

5. Conclusions are a few

Hopefully proving the benefits of evolution of error code handling into returns handling protocol does not need much convincing.

There are many real situations where the VALSTAT protocol can be successfully used. From a micro to the macro layers of the information systems .

As an common function call/return protocol, VALSTAT requires to be ubiquitously adopted to become truly instrumental to the widespread interoperability. From micro to macro levels. From inside the code to inter component calls. From inside an software project to inter systems situations.

VALSTAT protocol is multilingual in nature. Thus adopters coming from any imperative programming language are free to implement it in any way they wish too. For non coherent groups of adopters, the key requirement is: interoperability. 

Authors primary aim is to suggest widespread adoption of this paradigm. As shown VALSTAT is more than just solving the "error-signalling problem". It is an paradigm, instrumental in solving the often hard and orthogonal set of run-time operational requirements.

VALSTAT aims high. And it's proposed scope is rather wide. But it is a humble protocol. It is just an simple and effective way of building bridges over deeply fragmented parts of the vast global IT infrastructure. While in the same time imposing extremely little on adopters and their implementations and leaving the non-adopters to "proceed as before" if they wish too.

Obstacles to VALSTAT adoption are far from just technical. But here is at least an immediately usable attempt to chart the way out of IT legacy dictatorship.

6. References