Harden yjs container readiness and shutdown behavior

[AlexAndBear]

Description

This change upgrades the services/yjs container behavior for production-style operation.

It adds:

• container image HEALTHCHECK based on actual readiness (/healthz/ready) and WebSocket reachability
• graceful signal handling (SIGTERM/SIGINT/SIGQUIT) with a documented grace period
• shutdown draining behavior: readiness flips to unhealthy, new upgrades are rejected, then active connections are closed and document unload/flush paths run
• compose-level stop_grace_period for yjs, aligned with graceful shutdown behavior
• administrator documentation for restart policy, grace period, health semantics, and logging

Related Issue

• y.js container hygiene #3105

How Has This Been Tested?

• test environment: local development on macOS
• test case 1: pnpm --filter opencloud-yjs-server check:types
• test case 2: pnpm exec eslint services/yjs/src/server.ts services/yjs/src/healthcheck.ts
• test case 3: pnpm exec prettier --check services/yjs/src/server.ts services/yjs/src/healthcheck.ts services/yjs/README.md docker-compose.yml
• test case 4: docker compose config >/tmp/docker-compose.resolved.yml

Types of changes

• Bugfix
• Enhancement (a change that does not break existing code or deployments)
• Breaking change (a modification that affects current functionality)
• Technical debt (addressing code that needs refactoring or improvements)
• Tests (adding or improving tests)
• Documentation (updates or additions to documentation)
• Maintenance (like dependency updates or tooling adjustments)

[Copilot]

🟡 Changes recommended

There is a shutdown-grace configuration edge case that can produce unreliable shutdown behavior, and the PR description currently claims Compose health-gating changes that aren’t present in the diff.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Review details

Suppressed comments (1)

services/yjs/src/server.ts:6

• SHUTDOWN_GRACE_PERIOD_MS is parsed without validation. If the env var is unset/mistyped (e.g. "15s"), parseInt can yield NaN or a non-positive value, which makes the grace timer behavior unpredictable (including an immediate forced exit). Validate and fail fast (or clamp to a safe default) so shutdown semantics are reliable.

const SHUTDOWN_GRACE_PERIOD_MS = parseInt(process.env.SHUTDOWN_GRACE_PERIOD_MS ?? '15000', 10)

• Files reviewed: 5/5 changed files
• Comments generated: 1
• Review effort level: Lite