Add high-level SFS2X client/server API with typed models

[Zewsic]

Summary

This PR introduces a complete high-level application layer for ZewSFS, transforming it from a low-level protocol implementation into a developer-friendly framework with decorator-driven handlers, typed request/response models, and async client/server lifecycle management.

Key Changes

• New sfs2x.app module — High-level API built on top of the existing transport and protocol layers

  • SFSClient — Decorator-driven async client with @client.on_login(), @client.on_extension(command="..."), lifecycle hooks
  • SFSServer — Decorator-driven async server with per-session handlers and ServerSession state management
  • SFSModel — Typed dataclass-like models with SFS field annotations (UtfString, Int, etc.) that auto-serialize/deserialize to SFSObject
  • SystemRequest/SystemResponse and ExtensionRequest/ExtensionResponse — Base classes for typed request/response pairs
  • Built-in system models — HandshakeRequest, LoginRequest, LoginResponse, LoginErrorResponse, LogoutRequest, PingPongRequest and their responses

• Decorator handlers — Register async functions with @client.on_login(), @server.on_extension(command="..."), etc.

  • Automatic parameter binding from Message, SFSObject, ServerSession, or typed SFSModel subclasses
  • Union dispatch — handlers can declare req: LoginResponse | LoginErrorResponse and the first matching schema wins
  • raise to reply — handlers can raise ResponseModel(...) or return ResponseModel(...) to send replies

• Handler registry and dispatcher — HandlerRegistry stores decorated handlers; Dispatcher routes incoming messages to handlers by introspecting signatures and binding parameters

• Session objects — ClientSession and ServerSession provide state dicts, connection metadata, and send()/kick() methods

• Comprehensive test suite — test_app_models.py, test_app_dispatcher.py, test_app_integration.py covering model serialization, handler dispatch, and end-to-end client/server roundtrips

• Documentation — New docs/lowlevel.md and docs/protocol.md reference guides for the protocol and transport layers

• Updated README — Simplified introduction with high-level examples, feature list focused on the new API, and installation instructions

• Package exports — Top-level sfs2x/__init__.py re-exports the high-level API for convenience

Implementation Details

• SFSModel metaclass — Compiles field annotations at class definition time into FieldSpec tuples, generates __init__, __repr__, __eq__, and serialization methods
• Typed field binding — field(sfs_key, default=..., default_factory=...) marks attributes and binds them to SFSObject keys; supports nested models and optional fields
• Handler introspection — inspect_handler() walks function signatures and classifies parameters (MESSAGE, PAYLOAD, SESSION, MODEL, UNION_MODEL) for runtime binding
• Exception-based replies — Response models inherit from Exception so raise works; Reply(model) wrapper for non-Response models
• Lifecycle hooks — on_connect, on_disconnect, on_error callbacks fire at appropriate times in the dispatcher loop

All changes are backward compatible — the low-level sfs2x.core, sfs2x.protocol, and sfs2x.transport APIs remain unchanged.

https://claude.ai/code/session_01WDQmcTcMNhA9uDjpztRFao