Coverage for src / lexigram / contracts / core / invocation.py: 0%

1"""Transport-neutral invocation protocols. 

2 

3These protocols decouple the kernel invocation machinery from any specific 

4transport (HTTP, WebSocket, CLI, etc.) and are the foundation for Phase 3 

5transport decoupling. 

6""" 

7 

8from __future__ import annotations 

9 

10from typing import Any, Protocol, runtime_checkable 

11 

12 

13@runtime_checkable 

14class InvocationContextProtocol(Protocol): 

15 """Transport-neutral invocation context. 

16 

17 Represents the minimal shared surface of any invocation context — 

18 whether it originates from HTTP, a CLI command, a background task, etc. 

19 Concrete transports extend this with their own typed attributes. 

20 """ 

21 

22 

23@runtime_checkable 

24class InvocationHandlerProtocol(Protocol): 

25 """Transport-neutral handler protocol. 

26 

27 A handler receives an invocation context and produces a result. 

28 Implementations are responsible for executing the underlying business 

29 logic associated with an invocation. 

30 """ 

31 

32 async def handle(self, context: Any) -> Any: 

33 """Execute the handler for the given context. 

34 

35 Args: 

36 context: The invocation context (typed per transport). 

37 

38 Returns: 

39 The result of handler execution. 

40 """ 

41 ... 

42 

43 

44@runtime_checkable 

45class InvocationMiddlewareProtocol(Protocol): 

46 """Transport-neutral middleware protocol. 

47 

48 Middleware wraps handler execution with cross-cutting concerns such as 

49 logging, metrics, authentication, or tracing. Each middleware calls 

50 ``next_handler`` to continue the chain. 

51 """ 

52 

53 async def __call__(self, context: Any, next_handler: Any) -> Any: 

54 """Process the context and delegate to the next handler. 

55 

56 Args: 

57 context: The invocation context. 

58 next_handler: Callable representing the remainder of the chain. 

59 

60 Returns: 

61 The result from the next handler (possibly transformed). 

62 """ 

63 ... 

64 

65 

66@runtime_checkable 

67class InvocationPipelineProtocol(Protocol): 

68 """Transport-neutral pipeline protocol. 

69 

70 An immutable, composable pipeline of ``InvocationMiddlewareProtocol`` 

71 instances. ``add`` must return a **new** pipeline rather than mutating 

72 the existing one. 

73 

74 Example:: 

75 

76 pipeline = MyPipeline() 

77 pipeline = pipeline.add(LoggingMiddleware()) 

78 pipeline = pipeline.add(TracingMiddleware()) 

79 result = await pipeline.execute(context, handler) 

80 """ 

81 

82 def add(self, middleware: Any) -> InvocationPipelineProtocol: 

83 """Return a new pipeline with *middleware* appended. 

84 

85 Args: 

86 middleware: An invocation middleware instance. 

87 

88 Returns: 

89 A new pipeline with the middleware added. 

90 """ 

91 ... 

92 

93 async def execute(self, context: Any, handler: Any) -> Any: 

94 """Execute the pipeline with the given context and terminal handler. 

95 

96 Args: 

97 context: The invocation context. 

98 handler: The terminal handler called after all middleware. 

99 

100 Returns: 

101 The result produced by the terminal handler (possibly 

102 transformed by middleware). 

103 """ 

104 ... 

105 

106 

107__all__ = [ 

108 "InvocationContextProtocol", 

109 "InvocationHandlerProtocol", 

110 "InvocationMiddlewareProtocol", 

111 "InvocationPipelineProtocol", 

112]