hooks: add pre-access examples

- add some README.md to guide usage
- fix grpc example Makefile proto path

Author: sberthier

examples/hooks/file/README.md

@@ -0,0 +1,5 @@
+# Run file hook exemple
+
+    tusd -hooks-dir=./ -hooks-enabled-events=pre-create,pre-finish,pre-access,post-create,post-receive,post-terminate,post-finish
+
+Adapt enabled-events hooks list for your needs.

examples/hooks/file/pre-access

@@ -0,0 +1,10 @@
+#!/bin/sh
+
+# This example demonstrates how to read the hook event details
+# from stdin, and output debug messages.
+
+# We use >&2 to write debugging output to stderr. tusd
+# will forward these to its stderr. Any output from the
+# hook on stdout will be captured by tusd and interpreted
+# as a response.
+cat /dev/stdin | jq . >&2

examples/hooks/grpc/Makefile

@@ -1,2 +1,2 @@
-hook_pb2.py: ../../../cmd/tusd/cli/hooks/proto/v2/hook.proto
-	python3 -m grpc_tools.protoc --proto_path=../../../cmd/tusd/cli/hooks/proto/v2/ hook.proto --python_out=. --grpc_python_out=.
+hook_pb2.py: ../../../pkg/hooks/grpc/proto/hook.proto
+	python3 -m grpc_tools.protoc --proto_path=../../../pkg/hooks/grpc/proto/ hook.proto --python_out=. --grpc_python_out=.

examples/hooks/grpc/README.md

@@ -0,0 +1,7 @@
+# Run grpc hook exemple
+
+    python3 server.py
+
+    tusd -hooks-grpc=localhost:8000 -hooks-enabled-events=pre-create,pre-finish,pre-access,post-create,post-receive,post-terminate,post-finish
+
+Adapt enabled-events hooks list for your needs.

examples/hooks/grpc/hook_pb2.py

@@ -1,74 +1,50 @@
 # Generated by the gRPC Python protocol compiler plugin. DO NOT EDIT!
-"""Client and server classes corresponding to protobuf-defined services."""
 import grpc
 
 import hook_pb2 as hook__pb2
 
 
 class HookHandlerStub(object):
-    """The hook service definition.
-    """
+  """The hook service definition.
+  """
 
-    def __init__(self, channel):
-        """Constructor.
+  def __init__(self, channel):
+    """Constructor.
 
-        Args:
-            channel: A grpc.Channel.
-        """
-        self.InvokeHook = channel.unary_unary(
-                '/v2.HookHandler/InvokeHook',
-                request_serializer=hook__pb2.HookRequest.SerializeToString,
-                response_deserializer=hook__pb2.HookResponse.FromString,
-                )
+    Args:
+      channel: A grpc.Channel.
+    """
+    self.InvokeHook = channel.unary_unary(
+        '/proto.HookHandler/InvokeHook',
+        request_serializer=hook__pb2.HookRequest.SerializeToString,
+        response_deserializer=hook__pb2.HookResponse.FromString,
+        )
 
 
 class HookHandlerServicer(object):
-    """The hook service definition.
+  """The hook service definition.
+  """
+
+  def InvokeHook(self, request, context):
+    """InvokeHook is invoked for every hook that is executed. HookRequest contains the
+    corresponding information about the hook type, the involved upload, and
+    causing HTTP request.
+    The return value HookResponse allows to stop or reject an upload, as well as modifying
+    the HTTP response. See the documentation for HookResponse for more details.
     """
-
-    def InvokeHook(self, request, context):
-        """InvokeHook is invoked for every hook that is executed. HookRequest contains the
-        corresponding information about the hook type, the involved upload, and
-        causing HTTP request.
-        The return value HookResponse allows to stop or reject an upload, as well as modifying
-        the HTTP response. See the documentation for HookResponse for more details.
-        """
-        context.set_code(grpc.StatusCode.UNIMPLEMENTED)
-        context.set_details('Method not implemented!')
-        raise NotImplementedError('Method not implemented!')
+    context.set_code(grpc.StatusCode.UNIMPLEMENTED)
+    context.set_details('Method not implemented!')
+    raise NotImplementedError('Method not implemented!')
 
 
 def add_HookHandlerServicer_to_server(servicer, server):
-    rpc_method_handlers = {
-            'InvokeHook': grpc.unary_unary_rpc_method_handler(
-                    servicer.InvokeHook,
-                    request_deserializer=hook__pb2.HookRequest.FromString,
-                    response_serializer=hook__pb2.HookResponse.SerializeToString,
-            ),
-    }
-    generic_handler = grpc.method_handlers_generic_handler(
-            'v2.HookHandler', rpc_method_handlers)
-    server.add_generic_rpc_handlers((generic_handler,))
-
-
- # This class is part of an EXPERIMENTAL API.
-class HookHandler(object):
-    """The hook service definition.
-    """
-
-    @staticmethod
-    def InvokeHook(request,
-            target,
-            options=(),
-            channel_credentials=None,
-            call_credentials=None,
-            insecure=False,
-            compression=None,
-            wait_for_ready=None,
-            timeout=None,
-            metadata=None):
-        return grpc.experimental.unary_unary(request, target, '/v2.HookHandler/InvokeHook',
-            hook__pb2.HookRequest.SerializeToString,
-            hook__pb2.HookResponse.FromString,
-            options, channel_credentials,
-            insecure, call_credentials, compression, wait_for_ready, timeout, metadata)
+  rpc_method_handlers = {
+      'InvokeHook': grpc.unary_unary_rpc_method_handler(
+          servicer.InvokeHook,
+          request_deserializer=hook__pb2.HookRequest.FromString,
+          response_serializer=hook__pb2.HookResponse.SerializeToString,
+      ),
+  }
+  generic_handler = grpc.method_handlers_generic_handler(
+      'proto.HookHandler', rpc_method_handlers)
+  server.add_generic_rpc_handlers((generic_handler,))

examples/hooks/grpc/hook_pb2_grpc.py

@@ -37,6 +37,14 @@ def InvokeHook(self, hook_request, context):
                 hook_response.changeFileInfo.metaData['filename'] = metaData['filename']
                 hook_response.changeFileInfo.metaData['creation_time'] = time.ctime()
 
+
+	    # Example: Use the pre-access hook to print each upload access
+        if hook_request.type == 'pre-access':
+            mode    = hook_request.event.access.mode
+            id      = hook_request.event.access.files[0].id
+            size    = hook_request.event.access.files[0].size
+            print(f'Access {id} (mode={mode}, size={size} bytes)')
+
         # Example: Use the post-finish hook to print information about a completed upload,
         # including its storage location.
         if hook_request.type == 'post-finish':

examples/hooks/grpc/server.py

@@ -0,0 +1,7 @@
+# Run http hook exemple
+
+    python3 server.py
+
+    tusd -hooks-http=http://localhost:8000 -hooks-enabled-events=pre-create,pre-finish,pre-access,post-create,post-receive,post-terminate,post-finish
+
+Adapt enabled-events hooks list for your needs.

examples/hooks/http/README.md

@@ -50,6 +50,12 @@ def do_POST(self):
                     'creation_time': time.ctime(),
                 }
 
+	    # Example: Use the pre-access hook to print each upload access
+        if hook_request['Type'] == 'pre-access':
+            mode    = hook_request['Event']['Access']['Mode']
+            id      = hook_request['Event']['Access']['Files'][0]['ID']
+            size    = hook_request['Event']['Access']['Files'][0]['Size']
+            print(f'Access {id} (mode={mode}, size={size} bytes)')
 
         # Example: Use the post-finish hook to print information about a completed upload,
         # including its storage location.

examples/hooks/http/server.py

@@ -0,0 +1,7 @@
+# Run plugin hook exemple
+
+    make
+
+    tusd -hooks-http=./hook_handler -hooks-enabled-events=pre-create,pre-finish,pre-access,post-create,post-receive,post-terminate,post-finish
+
+Adapt enabled-events hooks list for your needs.