283 external mode web api contract config fetch external result ingestion by matheusmra · Pull Request #295 · webtech-network/autograder

matheusmra · 2026-04-16T21:56:40Z

[External Mode] Web API contract + M2M authentication for cloud integration

Summary

Adds two new protected endpoints to support GitHub Action external/private mode, along with a mandatory bearer-token authentication layer for machine-to-machine cloud integration.

What changed

New endpoints

`GET /api/v1/configs/id/{config_id}`

Fetches a full grading configuration by its internal database ID.
Required by the GitHub Action when operating in external mode, where only the grading_config_id is available.

Returns all fields needed to call build_pipeline(...):
template_name, criteria_config, setup_config, feedback_config, include_feedback, languages, external_assignment_id, version, is_active.

`POST /api/v1/submissions/external-results`

Ingests a grading result computed externally (e.g. inside the GitHub Action runner).

Creates a submissions row and a matching submission_results row. The result is immediately visible through the existing GET /submissions/{id} and GET /submissions/user/{external_user_id} endpoints.

Request payload:

Field	Required	Notes
`grading_config_id`	✅	Internal config ID
`external_user_id`	✅
`username`	✅
`language`	✅	Must be supported by the config
`status`	✅	`completed` or `failed`
`final_score`	✅	`>= 0`
`execution_time_ms`	✅	`>= 0`
`feedback`	—	Optional
`result_tree`	—	Optional
`focus`	—	Optional
`pipeline_execution`	—	Optional
`error_message`	—	Optional, for failed runs
`submission_metadata`	—	Optional repo/run metadata

M2M authentication

Both new endpoints are protected with a Bearer token dependency.

Token is read from AUTOGRADER_INTEGRATION_TOKEN environment variable (required — server raises ValueError at startup if unset)
Validation uses hmac.compare_digest to prevent timing attacks
Secrets are never logged
Returns 401 for missing or invalid token
All existing public endpoints are unaffected

New schemas

ExternalResultStatus — completed | failed
ExternalResultCreate — request body with Pydantic validation
ExternalResultResponse — response body

Docs

docs/API.md updated with:

Authentication section with setup instructions and usage examples
New endpoint documentation with request/response examples
markers on protected endpoints in the overview table

Tests

File	Coverage
`tests/web/test_external_results.py`	13 tests — success paths, 404, 400, 422
`tests/web/test_integration_auth.py`	13 tests — missing token, wrong token, valid token, public endpoints unaffected

All 51 web tests pass (test_external_results, test_integration_auth, test_routes, test_api_endpoints).

Files changed

web/config/auth.py                        new
web/api/deps.py                           modified
web/api/v1/grading_configs.py             modified
web/api/v1/submissions.py                 modified
web/schemas/submission.py                 modified
web/schemas/__init__.py                   modified
tests/web/test_external_results.py        new
tests/web/test_integration_auth.py        new
docs/API.md                               modified

Copilot

Pull request overview

Adds M2M-protected Web API support for “external/private mode” integrations (e.g., GitHub Action) by introducing bearer-token auth plus endpoints to fetch configs by internal ID and ingest externally computed grading results.

Changes:

Added Bearer-token auth dependency for integration-only endpoints.
Added GET /api/v1/configs/id/{config_id} for internal-ID config fetch.
Added POST /api/v1/submissions/external-results plus Pydantic schemas and web tests/docs for external result ingestion.

Reviewed changes

Copilot reviewed 9 out of 9 changed files in this pull request and generated 7 comments.

Show a summary per file

File	Description
`web/config/auth.py`	Adds integration token config loader/caching.
`web/api/deps.py`	Introduces `require_integration_token` FastAPI dependency using `HTTPBearer`.
`web/api/v1/grading_configs.py`	Adds protected config fetch endpoint by internal DB ID.
`web/api/v1/submissions.py`	Adds protected endpoint to ingest externally computed results into `submissions` + `submission_results`.
`web/schemas/submission.py`	Adds `ExternalResult*` request/response schemas and status enum.
`web/schemas/__init__.py`	Exports the new external-result schemas.
`tests/web/test_external_results.py`	Adds tests for config-by-id and external result ingestion behavior.
`tests/web/test_integration_auth.py`	Adds tests ensuring protected endpoints require token and public endpoints remain public.
`docs/API.md`	Documents auth setup and the new protected endpoints.

Copilot · 2026-04-16T22:04:17Z

+    cfg = IntegrationAuthConfig.__new__(IntegrationAuthConfig)
+    cfg.token = TEST_TOKEN
+    auth_module.integration_auth_config = cfg
+    yield
+    auth_module.integration_auth_config = cfg


The _set_integration_token autouse fixture sets auth_module.integration_auth_config but does not restore the previous value in teardown (it reassigns the same cfg). This can leak state across test modules and mask failures around missing/invalid env configuration; capture the old value before overriding and restore it after yield (often back to None).

Suggested change

cfg = IntegrationAuthConfig.__new__(IntegrationAuthConfig)

cfg.token = TEST_TOKEN

auth_module.integration_auth_config = cfg

yield

auth_module.integration_auth_config = cfg

old_integration_auth_config = getattr(auth_module, "integration_auth_config", None)

cfg = IntegrationAuthConfig.__new__(IntegrationAuthConfig)

cfg.token = TEST_TOKEN

auth_module.integration_auth_config = cfg

yield

auth_module.integration_auth_config = old_integration_auth_config

Copilot · 2026-04-16T22:04:17Z

+When the variable is **not set or empty**, the server will reject all requests to protected endpoints with `401 Unauthorized`. The token **must** be configured before using integration endpoints.
+


This paragraph states that when AUTOGRADER_INTEGRATION_TOKEN is unset or empty the server will reject protected requests with 401, but the implementation currently raises a ValueError when the env var is missing (which surfaces as a 500 unless handled) and it does not explicitly treat empty values as misconfiguration. Please update the docs to match actual behavior, or adjust the implementation to match the docs.

Copilot · 2026-04-16T22:04:17Z

+            raise ValueError(
+                "AUTOGRADER_INTEGRATION_TOKEN environment variable must be set"
+            )
+        self.token: str = os.environ["AUTOGRADER_INTEGRATION_TOKEN"]


IntegrationAuthConfig currently only checks that AUTOGRADER_INTEGRATION_TOKEN exists, but it allows an empty string. An empty token effectively locks out all integration requests and is easy to misconfigure; consider validating that the env var is non-empty (e.g., after .strip()), and fail fast with a clear error.

Suggested change

self.token: str = os.environ["AUTOGRADER_INTEGRATION_TOKEN"]

token = os.environ["AUTOGRADER_INTEGRATION_TOKEN"].strip()

if not token:

raise ValueError(

"AUTOGRADER_INTEGRATION_TOKEN environment variable must be non-empty"

)

self.token: str = token

Copilot · 2026-04-16T22:04:18Z

+    credentials: HTTPAuthorizationCredentials | None = Depends(_bearer_scheme),
+) -> None:
+    """Enforce Bearer-token auth on integration endpoints."""
+    config = get_integration_auth_config()


get_integration_auth_config() can raise ValueError when the integration token env var is unset, but require_integration_token does not handle this. That will surface as a 500 error on the protected endpoints and contradicts the documented behavior; either initialize/validate the auth config during app startup so misconfiguration fails fast, or catch the exception here and return a deterministic HTTP error with a clear message.

Suggested change

config = get_integration_auth_config()

try:

config = get_integration_auth_config()

except ValueError as exc:

raise HTTPException(

status_code=status.HTTP_503_SERVICE_UNAVAILABLE,

detail="Integration authentication is not configured",

) from exc

Copilot · 2026-04-16T22:04:18Z

+    now = datetime.now(timezone.utc)
+
+    # Create submission record (no files — externally graded)
+    submission_repo = SubmissionRepository(session)
+    db_submission = await submission_repo.create(
+        grading_config_id=grading_config.id,
+        external_user_id=payload.external_user_id,
+        username=payload.username,
+        submission_files={},
+        language=payload.language,
+        status=submission_status,
+        submission_metadata=payload.submission_metadata,
+    )
+    db_submission.graded_at = now


now = datetime.now(timezone.utc) produces a timezone-aware datetime, but elsewhere the code persists graded_at as a naive UTC timestamp (e.g., grading_service uses datetime.now(timezone.utc).replace(tzinfo=None)). Storing/returning mixed naive/aware datetimes can cause inconsistent API responses and can error on some DB backends; align this endpoint with the existing persistence convention for graded_at.

Copilot · 2026-04-16T22:04:18Z

+    cfg = IntegrationAuthConfig.__new__(IntegrationAuthConfig)
+    cfg.token = TEST_TOKEN
+    auth_module.integration_auth_config = cfg
+    yield
+    auth_module.integration_auth_config = cfg


The _set_integration_token autouse fixture sets auth_module.integration_auth_config but does not restore the previous value in teardown (it reassigns the same cfg). This can leak state across test modules and mask failures around missing/invalid env configuration; capture the old value before overriding and restore it after yield (often back to None).

Suggested change

cfg = IntegrationAuthConfig.__new__(IntegrationAuthConfig)

cfg.token = TEST_TOKEN

auth_module.integration_auth_config = cfg

yield

auth_module.integration_auth_config = cfg

old_integration_auth_config = auth_module.integration_auth_config

cfg = IntegrationAuthConfig.__new__(IntegrationAuthConfig)

cfg.token = TEST_TOKEN

auth_module.integration_auth_config = cfg

yield

auth_module.integration_auth_config = old_integration_auth_config

Copilot · 2026-04-16T22:04:19Z

+
+import pytest
+from httpx import AsyncClient, ASGITransport
+from unittest.mock import Mock, patch, AsyncMock


AsyncMock is imported but not used in this test module. Removing unused imports keeps tests easier to maintain and avoids lint failures in stricter CI setups.

Suggested change

from unittest.mock import Mock, patch, AsyncMock

from unittest.mock import Mock, patch

matheusmra · 2026-04-16T22:09:52Z

@ArthurCRodrigues ready for review :D

ArthurCRodrigues · 2026-04-17T15:53:03Z

Will review soon.

matheusmra added 4 commits April 16, 2026 18:50

feat: add ExternalResult schema

a8b2f28

feat: add get endpoint

5c8aa16

feat: Post external-results

9799cea

feat: Adding auth

7afee37

matheusmra linked an issue Apr 16, 2026 that may be closed by this pull request

[External Mode] M2M auth for integration endpoints #284

Closed

matheusmra requested a review from Copilot April 16, 2026 21:59

Copilot started reviewing on behalf of matheusmra April 16, 2026 22:00 View session

Copilot AI reviewed Apr 16, 2026

View reviewed changes

matheusmra added 2 commits April 16, 2026 19:08

feat: Copilot suggestions

edce51f

updating docs

332191f

matheusmra linked an issue Apr 16, 2026 that may be closed by this pull request

[External Mode] Web API contract: config fetch + external result ingestion #283

Closed

matheusmra requested a review from ArthurCRodrigues April 16, 2026 22:10

ArthurCRodrigues approved these changes Apr 21, 2026

View reviewed changes

ArthurCRodrigues merged commit 7ea1265 into main Apr 21, 2026
3 checks passed

ArthurCRodrigues deleted the 283-external-mode-web-api-contract-config-fetch-external-result-ingestion branch April 21, 2026 12:58

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

283 external mode web api contract config fetch external result ingestion#295

283 external mode web api contract config fetch external result ingestion#295
ArthurCRodrigues merged 6 commits intomainfrom
283-external-mode-web-api-contract-config-fetch-external-result-ingestion

matheusmra commented Apr 16, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI Apr 16, 2026

Uh oh!

Copilot AI Apr 16, 2026

Uh oh!

Copilot AI Apr 16, 2026

Uh oh!

Copilot AI Apr 16, 2026

Uh oh!

Copilot AI Apr 16, 2026

Uh oh!

Copilot AI Apr 16, 2026

Uh oh!

Copilot AI Apr 16, 2026

Uh oh!

matheusmra commented Apr 16, 2026

Uh oh!

ArthurCRodrigues commented Apr 17, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

		When the variable is not set or empty, the server will reject all requests to protected endpoints with `401 Unauthorized`. The token must be configured before using integration endpoints.

-        self.token: str = os.environ["AUTOGRADER_INTEGRATION_TOKEN"]
+        token = os.environ["AUTOGRADER_INTEGRATION_TOKEN"].strip()
+        if not token:
+            raise ValueError(
+                "AUTOGRADER_INTEGRATION_TOKEN environment variable must be non-empty"
+            )
+        self.token: str = token

-    config = get_integration_auth_config()
+    try:
+        config = get_integration_auth_config()
+    except ValueError as exc:
+        raise HTTPException(
+            status_code=status.HTTP_503_SERVICE_UNAVAILABLE,
+            detail="Integration authentication is not configured",
+        ) from exc

	from unittest.mock import Mock, patch, AsyncMock
	from unittest.mock import Mock, patch

Conversation

matheusmra commented Apr 16, 2026

[External Mode] Web API contract + M2M authentication for cloud integration

Summary

What changed

New endpoints

GET /api/v1/configs/id/{config_id}

POST /api/v1/submissions/external-results

M2M authentication

New schemas

Docs

Tests

Files changed

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Apr 16, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 16, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 16, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 16, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 16, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 16, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 16, 2026

Choose a reason for hiding this comment

Uh oh!

matheusmra commented Apr 16, 2026

Uh oh!

ArthurCRodrigues commented Apr 17, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

`GET /api/v1/configs/id/{config_id}`

`POST /api/v1/submissions/external-results`