Add /health endpoint for monitoring authentication and download state…

[JonasGao]

Add a health endpoint for docker container to show the user loged apple in or not

[stavros-k]

That would be great way to notify users instead of smtp.
ie I have already a uptime-kuma monitoring health of my containers and send me alerts if something is unhealthy

Awesome

[Copilot]

Pull request overview

This pull request adds a /health endpoint for Docker container monitoring to check authentication and download state. It includes a significant refactoring introducing Algebraic Data Types (ADTs) for better error handling throughout the codebase, particularly in authentication, photo service access, and download operations.

Changes:

• Added /health endpoint returning 200 when authenticated (NO_INPUT_NEEDED status) or 503 when authentication is needed
• Introduced comprehensive ADT system in pyicloud_ipd/response_types.py for type-safe error handling
• Refactored authentication flow, photo services, and download logic to use ADTs instead of exceptions
• Updated test infrastructure with new VCR cassettes for authentication scenarios
• Modified command-line tool to focus on keyring management only
• Added directory existence validation in CLI

Reviewed changes

Copilot reviewed 41 out of 62 changed files in this pull request and generated 11 comments.

Show a summary per file

File	Description
src/icloudpd/server/init.py	Added /health endpoint returning status based on authentication state
tests/test_health_check.py	New test suite for health endpoint with multiple status scenarios
src/pyicloud_ipd/response_types.py	New 790-line ADT definitions for all response types
src/pyicloud_ipd/session.py	Refactored response evaluation to return ADTs instead of raising exceptions
src/pyicloud_ipd/base.py	Major authentication refactoring using ADTs with factory pattern
src/pyicloud_ipd/services/photos.py	Photo service operations now return ADTs for error handling
src/icloudpd/authentication.py	Authentication flow updated to handle ADT results
src/icloudpd/download.py	Download logic refactored to use ADTs
src/icloudpd/autodelete.py	Autodelete operations updated with ADT error handling
src/icloudpd/cli.py	Added directory validation before processing
src/pyicloud_ipd/cmdline.py	Simplified to keyring management tool only
tests/*.py	Multiple test updates for new authentication and error handling patterns
tests/vcr_cassettes/*.yml	Updated/added VCR cassettes for test fixtures
.gitignore	Added *.har files to ignore list

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

The health endpoint returns 503 status when authentication is needed, which is semantically incorrect. HTTP 503 means "Service Unavailable" and typically indicates the server cannot handle requests due to maintenance or overload. For authentication/authorization issues, a more appropriate status would be 401 (Unauthorized) or 503 should be reserved for actual service unavailability. Consider returning 401 or another 4xx status code when authentication input is needed.

Suggested change

	return make_response("fail", 503)
	return make_response("fail", 401)

[Copilot]

The PR description says "loged" but should be "logged". This typo is visible in the PR title/description.

[Copilot]

The comment has a typo: "reponse" should be "response".

Suggested change

	" node in response. I cannot test SA on any of my accounts to get real server reponse and change app code accordingly"
	" node in response. I cannot test SA on any of my accounts to get real server response and change app code accordingly"

[Copilot]

assertTrue(a in b) cannot provide an informative message. Using assertIn(a, b) instead will give more informative messages.

Suggested change

	self.assertTrue("Can't overwrite existing cassette" in str(result.exception))
	self.assertIn("Can't overwrite existing cassette", str(result.exception))

[Copilot]

This comment appears to contain commented-out code.

Suggested change

	# def _authenticate_raw_password(self, password: str) -> None:
	# data = {
	# "accountName": self.apple_id,
	# "password": password,
	# "rememberMe": True,
	# "trustTokens": [],
	# }
	# if self.session_data.get("trust_token"):
	# data["trustTokens"] = [self.session_data.get("trust_token")]
	# headers = self._get_auth_headers(origin_referer_headers(self.AUTH_ROOT_ENDPOINT))
	# try:
	# # set observer with obfuscator
	# if self.response_observer:
	# rules = list(
	# chain(
	# self.cookie_obfuscate_rules,
	# self.header_obfuscate_rules,
	# self.header_pass_rules,
	# self.header_drop_rules,
	# self.auth_raw_body_obfuscate_rules,
	# self.auth_raw_body_drop_rules,
	# )
	# )
	# else:
	# rules = []

[Copilot]

This comment appears to contain commented-out code.

Suggested change

	# "rememberMe": True,
	# "trustTokens": [],
	# }
	# if self.session_data.get("trust_token"):
	# data["trustTokens"] = [self.session_data.get("trust_token")]
	# headers = self._get_auth_headers(origin_referer_headers(self.AUTH_ROOT_ENDPOINT))
	# try:
	# # set observer with obfuscator
	# if self.response_observer:
	# rules = list(
	# chain(
	# self.cookie_obfuscate_rules,
	# self.header_obfuscate_rules,
	# self.header_pass_rules,
	# self.header_drop_rules,
	# self.auth_raw_body_obfuscate_rules,
	# self.auth_raw_body_drop_rules,
	# )
	# )
	# else:
	# rules = []
	# with self.use_rules(rules):
	# response = self.session.post(
	# f"{self.AUTH_ENDPOINT}/signin",
	# params={"isRememberMeEnabled": "true"},
	# data=json.dumps(data),
	# headers=headers,
	# )
	# result = self.session.evaluate_response(response)
	# Note: a legacy authentication flow previously used here has been removed.
	# Refer to version control history if the old implementation details are needed.

[Copilot]

This comment appears to contain commented-out code.

Suggested change

	# chain(
	# self.cookie_obfuscate_rules,
	# self.header_obfuscate_rules,
	# self.header_pass_rules,
	# self.header_drop_rules,
	# self.auth_raw_body_obfuscate_rules,
	# self.auth_raw_body_drop_rules,
	# )
	# )
	# else:
	# rules = []
	# with self.use_rules(rules):
	# response = self.session.post(
	# f"{self.AUTH_ENDPOINT}/signin",
	# params={"isRememberMeEnabled": "true"},
	# data=json.dumps(data),
	# headers=headers,
	# )
	# result = self.session.evaluate_response(response)
	# match result:
	# case ResponseSuccess(_):
	# pass # Success, continue
	# case Response2SARequired(account_name):
	# raise PyiCloud2SARequiredException(account_name)
	# case ResponseServiceNotActivated(reason, code):
	# raise PyiCloudServiceNotActivatedException(reason, code)
	# case ResponseAPIError(reason, code):
	# raise PyiCloudAPIResponseException(reason, code)
	# case ResponseServiceUnavailable(reason):
	# raise PyiCloudServiceUnavailableException(reason)
	# Note: an older sign-in implementation using additional obfuscation and
	# response handling logic was removed here to avoid keeping commented-out code.
	# Refer to version control history if the previous logic is needed.

[Copilot]

This comment appears to contain commented-out code.

Suggested change

	# response = self.session.post(
	# f"{self.AUTH_ENDPOINT}/signin",
	# params={"isRememberMeEnabled": "true"},
	# data=json.dumps(data),
	# headers=headers,
	# )
	# result = self.session.evaluate_response(response)
	# match result:
	# case ResponseSuccess(_):
	# pass # Success, continue
	# case Response2SARequired(account_name):
	# raise PyiCloud2SARequiredException(account_name)
	# case ResponseServiceNotActivated(reason, code):
	# raise PyiCloudServiceNotActivatedException(reason, code)
	# case ResponseAPIError(reason, code):
	# raise PyiCloudAPIResponseException(reason, code)
	# case ResponseServiceUnavailable(reason):
	# raise PyiCloudServiceUnavailableException(reason)
	# except PyiCloudAPIResponseException as error:
	# msg = "Invalid email/password combination."
	# raise PyiCloudFailedLoginException(msg, error) from error

[Copilot]

Variable response is not used.

[Copilot]

This assignment to 'download_result' is unnecessary as it is redefined before this value is used.

Suggested change

	download_result = (
	DownloadMediaSkipped()
	) # Filtered files are skipped
	# Filtered files are skipped
	pass