docs: actions as service life-cycle hooks (lightbend#1909)

* Apply suggestions from code review

Co-authored-by: Renato Cavalcanti <[email protected]>

---------

Co-authored-by: Renato Cavalcanti <[email protected]>

docs/src/modules/java-protobuf/pages/actions.adoc

@@ -360,6 +360,23 @@ action returning and the `addItem` call from the action would lead to more items
 
 Such validation that depends on state can only be done safely while handling the command inside the entity.
 
+== Actions as Life-cycle Hooks
+
+An Action's gRPC method can be triggered automatically when some predefined service life-cycle event happens (currently, only on startup is available), serving as a custom hook. For such use, the method needs be annotated with a specific flag and its input type must be `google.protobuf.Empty` as shown below.
+
+IMPORTANT: The on startup hook is called every time a service instance boots up. This can happen for very different reasons: restarting / redeploying the service, scaling up to more instances or even without any user-driven action (e.g. Kalix Runtime versions being rolled out, infrastruture-related incidents, etc.). Therefore, you should carefully consider how you use this hook and its implementation.
+
+[source,proto]
+----
+include::example$java-protobuf-doc-snippets/src/main/proto/com/example/on_startup.proto[tag=hook]
+----
+<1> Only methods belonging to an Action can be configured as a hook.
+<2> The method must receive `google.protobuf.Empty` as input type.
+<3> This hook will be triggered once the instance startup is concluded (i.e. will be called 3 times if 3 instances are running).
+<4> Optionally, set the max amount of retries to 3.
+
+NOTE: If the call to the hook returns a failure and the `max_retries` is set to a value greater than the default value (`0`), a number of retry calls will be executed with a fixed delay up until the configure amount is reached.
+
 
 == Running Side Effects
 

docs/src/modules/java-protobuf/partials/actions.adoc

@@ -19,3 +19,4 @@ Actions can be triggered in multiple ways. For example, by:
 - an incoming message from a Topic.
 - an incoming event from an Event Sourced Entity, from within the same service or from a different service. 
 - state changes notification from a Value Entity on the same service.
+- a service life-cycle event (e.g. on startup).

samples/java-protobuf-doc-snippets/src/main/proto/com/example/on_startup.proto

@@ -0,0 +1,35 @@
+// Copyright 2021 Lightbend Inc.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+//
+// tag::counter-topic[]
+syntax = "proto3";
+package com.example.actions;
+
+import "kalix/annotations.proto";
+import "google/protobuf/empty.proto";
+
+// tag::hook[]
+service OnStartup {
+  option (kalix.codegen) = {
+    action: {} // <1>
+  };
+
+  rpc Init (google.protobuf.Empty) returns (google.protobuf.Empty) { // <2>
+    option (kalix.method).trigger = {
+      on: STARTUP, // <3>
+      max_retries: 3 // <4>
+    };
+  }
+}
+// end::hook[]