Introduction to the service model
Development and deployment of a Golem service
How can I host services in the Golem network?
Golem allows you to launch and control interactive services. Contrary to batch processing tasks - which execute certain computations and finish once the results are ready - a service is, in general Golem terms, a process which runs on a node controlled by a Provider, based on the Agreement with a Requestor, and responds to requests (passed either via Golem network, or totally outside of Golem network's visibility), until it is explicitly stopped (usually by a Requestor).
In the Golem service model, the Requestor Agent application specifies the service which is to be instantiated and then controls the service instance throughout its lifecycle in the Golem network.
Our Services API provides an abstraction over Golem low-level APIs, which is aimed at making the building of service-oriented applications straightforward for a developer. The abstraction is based on a logical concept of a Service, in other words, an entity that implements the logic of a service application, and which, from Requestor's perspective, follows a certain sequence of states:
Transitions from one state to another take place as a result of certain events. The events may be triggered by a Requestor (RunService), Provider (AgreementTerminated), or may be a result of an external phenomenon (like errors of varying nature). Golem SDK's service programming model allows the developer to specify logic that is to be executed in subsequent "active" states of the Service's lifecycle (
Stopping). The HL API controls the transitions between states and hides the "plumbing" of Golem mechanics so that the developer can focus on their service's details.
The developer of a Golem service application needs to follow a certain pattern to implement fundamental aspects of service definition and control. A Service application includes an ExeUnit running on the Provider node, and a Requestor exercising control over that ExeUnit via Golem APIs. The ExeUnit can be eg. a VM hosting a specific payload application, or a custom ExeUnit controller/wrapper which integrates a third-party service software with the Golem ecosystem. In any case, the Service provisioned on the Golem network will require certain aspects to be specified in the Requestor Agent application.
In order to define a Golem Service, the developer must create a class/object to indicate the fundamental aspects of the Service to be provisioned. The class must include methods responsible for payload specification (the details of the Demand indicating eg. the ExeUnit/runtime to be sought on the market), and logic to be executed in "active" states of the service lifecycle.
The code snippets below are illustrating a very basic service (a
SimpleService), hosted in a standard Golem VM runtime, where service "requests" are the shell commands executed repeatedly on the VM while the service is running.
The Requestor Agent app must define the "payload" - the detailed specification of the service which is to be provisioned. This specification is then wrapped in a
Demandstructure and published on the Golem market.
async def get_payload():
return await vm.repo(
A HL API library controls all aspects of acquisition of suitable Providers, negotiations, and instantiation of Activities. The app needs to indicate the actions to be executed in subsequent "active" states of the Service's lifecycle.
Once a Golem activity starts and the Service instance begins its life, the Requestor Agent must indicate all actions to be executed in order to set up the service.
async def start(self):
# perform the initialization of the Service
async for script in super().start():
script = self._ctx.new_script()
start()method follows a 'work generator' pattern. It uses a
Scriptinstance (acquired via
_ctx- the activity's work context) to build a sequence of actions which then gets returned to the service execution engine to be asynchronously relayed to the Provider's runtime. Please take a look at the methods provided by
Scriptobjects to get familiar with the possible work steps that can be performed via Golem APIs:
start()sequence of actions is executed only once in Service's lifecycle and must result either with success, or indication of failure, in which case, depending on the
respawn_unstarted_instancesflag of the
Golem.run_service()call, the Service's startup is retried on another provider if the flag is
Trueor immediately moves to
Once started, the Service transitions to the Running mode - a normal state of operation. In this state, the Requestor Agent may for example; monitor and control the service (either via Golem APIs or contacting the service directly via other means).
async def run(self):
script = self._ctx.new_script()
stats_result = script.run("/golem/run/simple_service.py", "--stats") # idx 0
stats = (await stats_result).stdout.strip()
Note that the Requestor Agent may at some point decide to end the service while it is in
Runningstate - this ends the actions specified for
Runningstate and triggers the transition to
In case the service gets halted, either by Requestor's decision or due to Provider-triggered termination, provided the activity (and thus, the attached
WorkContext) is still available, the Service moves to a
Stoppingstate, in which a Requestor Agent still may have an ability to e.g. recover some artifacts from the service instance, or perform some general clean sweep.
async def shutdown(self):
script = self._ctx.new_script()
Note that the
Stoppingactions are executed only once in Service's lifecycle.
In a situation where the termination happens abruptly - e.g. because the provider running the service stops responding or has already terminated the respective activity, Golem won't be able to transition the instance to the
stoppingstate but rather directly to the
terminatedone. In this case, the
shutdownhandler won't be executed.
Once a service specification class/object is defined, the service can be provisioned on the Golem network. This is done via a
Golemexecution processor object, which hides all the technical nuances of market interaction, activity tracking, and service state lifecycle:
async with Golem(
) as golem:
cluster = await golem.run_service(
expiration=datetime.now(timezone.utc) + timedelta(minutes=15))
Golemcall returns a
Clusterof (in this case)
SimpleServiceobjects, each representing an instance of the service, as provisioned on the Golem network. The
Clustercan be used to control the state of the services (e.g. to stop services when required).
This is all it takes to build a Requestor Agent for rudimentary VM-based service. Soon, we'll show you a bit more sophisticated service examples, eg. including custom runtimes. Stay tuned!
For now, you may wish to jump to:
Have fun exploring the new Service API!