diff --git a/documents/docs/networking/commands/README.md b/documents/docs/networking/commands/README.md index 2784975..391ec9d 100644 --- a/documents/docs/networking/commands/README.md +++ b/documents/docs/networking/commands/README.md @@ -6,7 +6,7 @@ Each command consists of four classes: a **Parser**, a **Request**, a **Handler* The infrastructure for routing and dispatching commands lives in the `network/` layer and is intentionally kept generic. The concrete implementations for each command live in `app/commands/` and are wired together at startup in `ServerApp`. -![Overview of all components directly related to executing requests](/documents/images/docs/networking/commands/overview.svg) +![Overview of all components directly related to executing requests](../../../images/docs/networking/commands/overview.png) ## Contents ### Guides diff --git a/documents/docs/networking/commands/commands-deep-dive.md b/documents/docs/networking/commands/commands-deep-dive.md index 3999384..5a0178c 100644 --- a/documents/docs/networking/commands/commands-deep-dive.md +++ b/documents/docs/networking/commands/commands-deep-dive.md @@ -10,11 +10,11 @@ An incoming request travels through two sequential pipelines: **parsing** and ** The parsing pipeline converts a stringly-typed `PrimitiveRequest` into a strongly-typed `Request` subclass. The execution pipeline routes that typed request to the correct handler, which produces a `Response`. -![Sequence diagram of all involved components to process and respond to an incoming request](/documents/images/docs/networking/commands/sequence_diagram.svg) +Sequence diagram of all involved components to process and respond to an incoming request ## Parsing Pipeline ### `CommandParser` -![Class diagram of the CommandParser](/documents/images/docs/networking/commands/command_parser.svg) +Class diagram of the CommandParser The `CommandParser` is a single-method interface responsible for converting a `PrimitiveRequest` into a concrete, typed `Request` subclass. Implementations live in `app/commands//` and are registered by name in `CommandParserDispatcher`. @@ -25,7 +25,7 @@ If a required parameter is absent, `RequestParameterAccessor.require(...)` throw Parsers **do not** perform any domain logic. Their only job is extraction and type conversion. ### `CommandParserDispatcher` -![Class diagram of CommandParserDispatcher](/documents/images/docs/networking/commands/command_parser_dispatcher.svg) +Class diagram of CommandParserDispatcher The `CommandParserDispatcher` holds a map from command name strings (e.g. `"PING"`) to their corresponding `CommandParser`. When the `SessionReader` receives a `PrimitiveRequest`, it calls `dispatcher.parse(...)`, which looks up the parser by the request's command string and delegates parsing. @@ -33,7 +33,7 @@ When the `SessionReader` receives a `PrimitiveRequest`, it calls `dispatcher.par If no parser is registered for the command name, `parse(...)` throws an `UnknownCommandException`, which `SessionReader` catches and converts into an `UNKNOWN_COMMAND` error response for the client. ### `RequestParameterAccessor` -![Class diagram of RequestParameterAccessor](/documents/images/docs/networking/commands/request_parameter_accessor.svg) +Class diagram of RequestParameterAccessor The `RequestParameterAccessor` is a helper provided to parsers for reading typed parameter values from a `PrimitiveRequest`. It indexes the parameter list by key on construction for O(1) lookups. @@ -54,7 +54,7 @@ The `RequestParameterAccessor` wraps it in a `ParameterParseException`. ## Execution Pipeline ### `Request` -![Class diagram of Request](/documents/images/docs/networking/commands/request.svg) +Class diagram of the Request The `Request` is the abstract base class for all typed command requests. It carries a `RequestContext`, an immutable record containing the originating `SessionId` and the numeric `requestId`. Both of which are later used by the handler to direct the response to the correct session. @@ -62,7 +62,7 @@ Both of which are later used by the handler to direct the response to the correc Concrete subclasses add command-specific fields, all set via constructor. Requests are immutable value objects. They carry data, not behaviour. ### `CommandHandler` -![Class diagram of CommandHandler](/documents/images/docs/networking/commands/command_handler.svg) +Class diagram of the CommandHandler The `CommandHandler` is a single-method interface responsible for executing a typed request. The handler contains the domain logic: reading from registries and managers, modifying state, and dispatching a response via the `ResponseDispatcher`. @@ -71,7 +71,7 @@ Handlers receive their dependencies (the `ResponseDispatcher`, registries and ma This keeps them fully testable without the network layer. ### `CommandRouter` -![Class diagram of CommandRouter](/documents/images/docs/networking/commands/command_router.svg) +Class diagram of the CommandRouter The `CommandRouter` maps `Request` subclasses to their handlers using the request's runtime class as the key. The type safety of `register(...)` ensures that a handler can only be registered for the exact type it is parameterised on. @@ -81,7 +81,7 @@ If no handler is registered for the given request type, `execute(...)` throws `U Unlike `UnknownCommandException` (which covers unknown command strings), this exception indicates a programming error i.e. a parser was registered without a corresponding handler. ## Response Types -![Class diagram of the response interface and built-in implementations](/documents/images/docs/networking/commands/response_types.svg) +Class diagram of the response interface and built-in implementations The `Response` is the abstract base for all server responses. Its two concrete branches are `SuccessResponse` (prefix `+OK`) and `ErrorResponse` (prefix `-ERR`). Command-specific responses extend `SuccessResponse` and populate the body using the `ResponseBodyBuilder`. diff --git a/documents/docs/networking/server-architecture.md b/documents/docs/networking/server-architecture.md index 8537382..48238fa 100644 --- a/documents/docs/networking/server-architecture.md +++ b/documents/docs/networking/server-architecture.md @@ -26,8 +26,7 @@ Responses start with `+OK` on success or `-ERR` when something goes wrong. Comma We don't use HTTP, there's no JSON body, no headers. Just a raw socket, a text stream, and a clearly defined set of commands. ## Core Components & Their Roles - -![PlantUML diagramm of all components outlined in this document](/documents/images/docs/networking/server-architecure/networking_components.svg) +PlantUML diagram of all components outlined in this document Here's a quick rundown of the main building blocks: diff --git a/documents/images/docs/networking/commands/command_handler.png b/documents/images/docs/networking/commands/command_handler.png new file mode 100644 index 0000000..ed94bcb Binary files /dev/null and b/documents/images/docs/networking/commands/command_handler.png differ diff --git a/documents/images/docs/networking/commands/command_handler.svg b/documents/images/docs/networking/commands/command_handler.svg deleted file mode 100644 index 750344e..0000000 --- a/documents/images/docs/networking/commands/command_handler.svg +++ /dev/null @@ -1 +0,0 @@ -CommandHandlerT extends Requestexecute(request: T): void \ No newline at end of file diff --git a/documents/images/docs/networking/commands/command_parser.png b/documents/images/docs/networking/commands/command_parser.png new file mode 100644 index 0000000..f0acee2 Binary files /dev/null and b/documents/images/docs/networking/commands/command_parser.png differ diff --git a/documents/images/docs/networking/commands/command_parser.svg b/documents/images/docs/networking/commands/command_parser.svg deleted file mode 100644 index 357abf4..0000000 --- a/documents/images/docs/networking/commands/command_parser.svg +++ /dev/null @@ -1 +0,0 @@ -CommandParserT extends Requestparse(primitiveRequest: PrimitiveRequest): T \ No newline at end of file diff --git a/documents/images/docs/networking/commands/command_parser_dispatcher.png b/documents/images/docs/networking/commands/command_parser_dispatcher.png new file mode 100644 index 0000000..2097f6d Binary files /dev/null and b/documents/images/docs/networking/commands/command_parser_dispatcher.png differ diff --git a/documents/images/docs/networking/commands/command_parser_dispatcher.svg b/documents/images/docs/networking/commands/command_parser_dispatcher.svg deleted file mode 100644 index 7f61e6e..0000000 --- a/documents/images/docs/networking/commands/command_parser_dispatcher.svg +++ /dev/null @@ -1 +0,0 @@ -CommandParserDispatcherparsers: Map<String, CommandParser>register(command: String, parser: CommandParser): voidparse(primitiveRequest: PrimitiveRequest): Request \ No newline at end of file diff --git a/documents/images/docs/networking/commands/command_router.png b/documents/images/docs/networking/commands/command_router.png new file mode 100644 index 0000000..b165b23 Binary files /dev/null and b/documents/images/docs/networking/commands/command_router.png differ diff --git a/documents/images/docs/networking/commands/command_router.svg b/documents/images/docs/networking/commands/command_router.svg deleted file mode 100644 index 7dc0117..0000000 --- a/documents/images/docs/networking/commands/command_router.svg +++ /dev/null @@ -1 +0,0 @@ -CommandRouterhandlers: Map<Class<? extends Request>, CommandHandler<?>>register(requestClass: Class<T>, handler: CommandHandler<T>): voidexecute(request: Request): void \ No newline at end of file diff --git a/documents/images/docs/networking/commands/overview.png b/documents/images/docs/networking/commands/overview.png new file mode 100644 index 0000000..b10311f Binary files /dev/null and b/documents/images/docs/networking/commands/overview.png differ diff --git a/documents/images/docs/networking/commands/overview.svg b/documents/images/docs/networking/commands/overview.svg deleted file mode 100644 index 8bc887d..0000000 --- a/documents/images/docs/networking/commands/overview.svg +++ /dev/null @@ -1 +0,0 @@ -network/ (infrastructure)app/commands/<name>/ (per command)«record»PrimitiveRequestCommandParserT extends RequestCommandHandlerT extends RequestCommandParserDispatcherCommandRouterRequestResponseExampleParserCommandParserExampleRequestRequestExampleHandlerCommandHandlerExampleResponseResponseroutesparsed byroutes toparses toroutesroutes toexecuted bycreatesparses toexecuted byproduces \ No newline at end of file diff --git a/documents/images/docs/networking/commands/request.png b/documents/images/docs/networking/commands/request.png new file mode 100644 index 0000000..bbc2d9c Binary files /dev/null and b/documents/images/docs/networking/commands/request.png differ diff --git a/documents/images/docs/networking/commands/request.svg b/documents/images/docs/networking/commands/request.svg deleted file mode 100644 index c4d8826..0000000 --- a/documents/images/docs/networking/commands/request.svg +++ /dev/null @@ -1 +0,0 @@ -Requestcontext: RequestContextgetContext(): RequestContextgetSessionId(): SessionIdgetRequestId(): int \ No newline at end of file diff --git a/documents/images/docs/networking/commands/request_parameter_accessor.png b/documents/images/docs/networking/commands/request_parameter_accessor.png new file mode 100644 index 0000000..9134ce2 Binary files /dev/null and b/documents/images/docs/networking/commands/request_parameter_accessor.png differ diff --git a/documents/images/docs/networking/commands/request_parameter_accessor.svg b/documents/images/docs/networking/commands/request_parameter_accessor.svg deleted file mode 100644 index d9a6bce..0000000 --- a/documents/images/docs/networking/commands/request_parameter_accessor.svg +++ /dev/null @@ -1 +0,0 @@ -RequestParameterAccessorindex: Map<String, String>RequestParameterAccessor(parameters: List<RequestParameters>)require(key: String): Stringrequire(key: String, parser: ThrowingParser<T>): Toptional(key: String, defaultValue: String): Stringoptional(key: String, defaultValue: T, parser: ThrowingParser<T>): T \ No newline at end of file diff --git a/documents/images/docs/networking/commands/response_types.png b/documents/images/docs/networking/commands/response_types.png new file mode 100644 index 0000000..1f7e618 Binary files /dev/null and b/documents/images/docs/networking/commands/response_types.png differ diff --git a/documents/images/docs/networking/commands/response_types.svg b/documents/images/docs/networking/commands/response_types.svg deleted file mode 100644 index 142696c..0000000 --- a/documents/images/docs/networking/commands/response_types.svg +++ /dev/null @@ -1 +0,0 @@ -Responsecontext: RequestContextbody: ResponseBodyprefix(): StringgetSessionId(): SessionIdgetRequestId(): intgetBody(): ResponseBodySuccessResponseprefix(): String (+OK)OkResponseErrorResponseprefix(): String (-ERR) \ No newline at end of file diff --git a/documents/images/docs/networking/commands/sequence_diagram.png b/documents/images/docs/networking/commands/sequence_diagram.png new file mode 100644 index 0000000..374596c Binary files /dev/null and b/documents/images/docs/networking/commands/sequence_diagram.png differ diff --git a/documents/images/docs/networking/commands/sequence_diagram.svg b/documents/images/docs/networking/commands/sequence_diagram.svg deleted file mode 100644 index b838d09..0000000 --- a/documents/images/docs/networking/commands/sequence_diagram.svg +++ /dev/null @@ -1 +0,0 @@ -SessionReaderCommandParserDispatcherCommandParser.T.CommandRouterCommandHandler.T.ResponseDispatcherSessionReaderSessionReaderCommandParserDispatcherCommandParserDispatcherCommandParser<T>CommandParser<T>CommandRouterCommandRouterCommandHandler<T>CommandHandler<T>ResponseDispatcherResponseDispatcherparse(primitiveRequest)parse(primitiveRequest)ExampleRequestRequestexecute(request)execute(ExampleRequest)dispatch(ExampleRequest) \ No newline at end of file diff --git a/documents/images/docs/networking/server-architecure/networking_components.png b/documents/images/docs/networking/server-architecure/networking_components.png new file mode 100644 index 0000000..8c98399 Binary files /dev/null and b/documents/images/docs/networking/server-architecure/networking_components.png differ diff --git a/documents/images/docs/networking/server-architecure/networking_components.svg b/documents/images/docs/networking/server-architecure/networking_components.svg deleted file mode 100644 index 9db9f6d..0000000 --- a/documents/images/docs/networking/server-architecure/networking_components.svg +++ /dev/null @@ -1 +0,0 @@ -NetworkManager+start(port: int)Session-id: SessionId+Session(id: SessionId)+getId(): SessionId+run()+send(response: String)SessionId-value: UUID+SessionId()+SessionId(value: UUID)SessionManager-sessions: Map<UUID, Session>+add(session: Session)+getById(id: UUID): Session+remove(id: UUID)RawRequest-session: Session-rawMessage: StringResponse+encode(): StringTokenizer+tokenize(input: String): List<String>ProtocolParser+parse(raw: RawRequest): PrimitiveRequestPrimitiveRequest-command: String-arguments: Map<String, String>«per command»CommandParser+parse(primitive: PrimitiveRequest): Request«per command»Request-session: SessionCommandRouter+route(request: Request)«per command»CommandHandler+handle(request: Request)SuccessResponseErrorResponsecreatesadds session toidentified bycreatessendsmanagespassed tousesproducespassed toproducesdispatches toreceives \ No newline at end of file