class Quark::Mdk::Session

A session provides a lightweight sequential context that a microservice can use in the context of any application framework in order to manage its interactions with other microservices. It provides simple APIs for service resolution, distributed tracing, and circuit breakers.

A microservices architecture enables small self contained units of business logic to be implemented by separate teams working on isolated services based on the languages and frameworks best suited for their problem domain.

Any given microservice will contain sequential business logic implemented in a variety of ways depending on the application framework chosen. For example it may be a long running thread, a simple blocking request handler, or a chained series of reactive handlers in an async environment.

For the most part this business logic can be implemented exactly as prescribed by the application framework of choice, however in a microservices architecture, some special care needs to be taken when this business logic interacts with other microservices.

Because microservices are updated with much higher frequency than normal web applications, the interactions between them form key points that require extra care beyond normal web interactions in order to avoid creating a system that is both extremely fragile, unreliable, and opaque.

Realtime service resolution, distributed tracing, and resilience heuristics such as circuit breakers provide the foundational behavior required at these interaction points. These capabilites must be combined with the defensive coding practice of intelligent fallback behavior when remote services are unavailable or misbehaving, in order to build a robust microservice application.

Because of this, a session is expected to be created and made available to all business logic within a given microservice, e.g. on a per request basis, as a thread local, part of a context object, etc depending on the application framework of choice.

Public Class Methods

new() click to toggle source

# File output/rb/mdk-2.0/lib/mdk.rb, line 291
def initialize()
    self.__init_fields__

    nil
end

Public Instance Methods

__init_fields__() click to toggle source

# File output/rb/mdk-2.0/lib/mdk.rb, line 570
def __init_fields__()
    

    nil
end

critical(category, text) click to toggle source

Record a log entry at the CRITICAL logging level.

# File output/rb/mdk-2.0/lib/mdk.rb, line 321
def critical(category, text)
    raise NotImplementedError, '`Session.critical` is an abstract method'

    nil
end

debug(category, text) click to toggle source

Record a log entry at the DEBUG logging level.

# File output/rb/mdk-2.0/lib/mdk.rb, line 357
def debug(category, text)
    raise NotImplementedError, '`Session.debug` is an abstract method'

    nil
end

error(category, text) click to toggle source

Record a log entry at the ERROR logging level.

# File output/rb/mdk-2.0/lib/mdk.rb, line 330
def error(category, text)
    raise NotImplementedError, '`Session.error` is an abstract method'

    nil
end

externalize() click to toggle source

Returns an externalized representation of the distributed session.

# File output/rb/mdk-2.0/lib/mdk.rb, line 312
def externalize()
    raise NotImplementedError, '`Session.externalize` is an abstract method'

    nil
end

fail_interaction(message) click to toggle source

Record an interaction as failed.

This will update circuit breaker state for the remote nodes, as well as reporting all nodes involved to the tracing system.

# File output/rb/mdk-2.0/lib/mdk.rb, line 453
def fail_interaction(message)
    raise NotImplementedError, '`Session.fail_interaction` is an abstract method'

    nil
end

finish_interaction() click to toggle source

Finish an interaction.

This marks an interaction as completed.

# File output/rb/mdk-2.0/lib/mdk.rb, line 465
def finish_interaction()
    raise NotImplementedError, '`Session.finish_interaction` is an abstract method'

    nil
end

getEnvironment() click to toggle source

Return the session's Environment.

# File output/rb/mdk-2.0/lib/mdk.rb, line 564
def getEnvironment()
    raise NotImplementedError, '`Session.getEnvironment` is an abstract method'

    nil
end

getProperty(property) click to toggle source

Return the value of a property from the distributed session.

# File output/rb/mdk-2.0/lib/mdk.rb, line 530
def getProperty(property)
    raise NotImplementedError, '`Session.getProperty` is an abstract method'

    nil
end

getRemainingTime() click to toggle source

Return how many seconds until the session ought to end.

This will only be accurate across multiple servers insofar as their clocks are in sync.

If a timeout has not been set the result will be null.

# File output/rb/mdk-2.0/lib/mdk.rb, line 521
def getRemainingTime()
    raise NotImplementedError, '`Session.getRemainingTime` is an abstract method'

    nil
end

hasProperty(property) click to toggle source

Return whether the distributed session has a property.

# File output/rb/mdk-2.0/lib/mdk.rb, line 555
def hasProperty(property)
    raise NotImplementedError, '`Session.hasProperty` is an abstract method'

    nil
end

info(category, text) click to toggle source

Record a log entry at the INFO logging level.

# File output/rb/mdk-2.0/lib/mdk.rb, line 348
def info(category, text)
    raise NotImplementedError, '`Session.info` is an abstract method'

    nil
end

inject() click to toggle source

Grabs the encoded context.

# File output/rb/mdk-2.0/lib/mdk.rb, line 303
def inject()
    raise NotImplementedError, '`Session.inject` is an abstract method'

    nil
end

interact(callable) click to toggle source

This is a convenience API that will perform #start_interaction() followed by callable(ssn) followed by #finish_interaction().

# File output/rb/mdk-2.0/lib/mdk.rb, line 478
def interact(callable)
    raise NotImplementedError, '`Session.interact` is an abstract method'

    nil
end

resolve(service, version) click to toggle source

Locate a compatible service instance.

Uses a minimum of 10 seconds and the timeout set on the session.

# File output/rb/mdk-2.0/lib/mdk.rb, line 395
def resolve(service, version)
    raise NotImplementedError, '`Session.resolve` is an abstract method'

    nil
end

resolve_async(service, version) click to toggle source

Locate a compatible service instance asynchronously. The result is returned as a promise.

# File output/rb/mdk-2.0/lib/mdk.rb, line 415
def resolve_async(service, version)
    raise NotImplementedError, '`Session.resolve_async` is an abstract method'

    nil
end

resolve_until(service, version, timeout) click to toggle source

Locate a compatible service instance with a non-default timeout.

# File output/rb/mdk-2.0/lib/mdk.rb, line 405
def resolve_until(service, version, timeout)
    raise NotImplementedError, '`Session.resolve_until` is an abstract method'

    nil
end

route(service, version, target, targetVersion) click to toggle source

EXPERIMENTAL; requires MDK_EXPERIMENTAL=1 environment variable to function.

Override service resolution for the current distributed session. All attempts to resolve service, version will be replaced with an attempt to resolve target, targetVersion. This effect will be propogated to any downstream services involved in the distributed session.

# File output/rb/mdk-2.0/lib/mdk.rb, line 383
def route(service, version, target, targetVersion)
    raise NotImplementedError, '`Session.route` is an abstract method'

    nil
end

setDeadline(seconds) click to toggle source

Set how many seconds the session is expected to live from this point.

If a timeout has previously been set the new timeout will only be used if it is lower than the existing timeout.

The MDK will not enforce the timeout. Rather, it provides the information to any process or server in the same session (even if they are on different machines). By passing this timeout to blocking APIs you can ensure timeouts are enforced across a whole distributed session.

# File output/rb/mdk-2.0/lib/mdk.rb, line 497
def setDeadline(seconds)
    raise NotImplementedError, '`Session.setDeadline` is an abstract method'

    nil
end

setProperty(property, value) click to toggle source

Set a property on the distributed session.

The key should be prefixed with a namespace so that it doesn't conflict with built-in properties, e.g. 'examplenamespace:myproperty' instead of 'myproperty'.

The value should be JSON serializable.

# File output/rb/mdk-2.0/lib/mdk.rb, line 546
def setProperty(property, value)
    raise NotImplementedError, '`Session.setProperty` is an abstract method'

    nil
end

setTimeout(seconds) click to toggle source

DEPRECATED, use setDeadline().

# File output/rb/mdk-2.0/lib/mdk.rb, line 506
def setTimeout(seconds)
    raise NotImplementedError, '`Session.setTimeout` is an abstract method'

    nil
end

start_interaction() click to toggle source

Start an interaction with a remote service.

The session tracks any nodes resolved during an interactin with a remote service.

The service resolution API permits a compatible instance of the service to be located. In addition, it tracks which exact instances are in use during any interaction. Should the interaction fail, circuit breaker state is updated for those nodes, and all involved instances involved are reported to the tracing services.

This permits realtime reporting of integration issues when services are updated, and also allows circuit breakers to mitigate the impact of any such issues.

# File output/rb/mdk-2.0/lib/mdk.rb, line 439
def start_interaction()
    raise NotImplementedError, '`Session.start_interaction` is an abstract method'

    nil
end

trace(level) click to toggle source

EXPERIMENTAL: Set the logging level for the session.

# File output/rb/mdk-2.0/lib/mdk.rb, line 366
def trace(level)
    raise NotImplementedError, '`Session.trace` is an abstract method'

    nil
end

warn(category, text) click to toggle source

Record a log entry at the WARN logging level.

# File output/rb/mdk-2.0/lib/mdk.rb, line 339
def warn(category, text)
    raise NotImplementedError, '`Session.warn` is an abstract method'

    nil
end