Files
Dashboard_Projects_Management/projects/test_documentation.py
T

271 lines
17 KiB
Python

import hashlib
import json
import subprocess
import tempfile
from pathlib import Path
from datetime import timedelta
from unittest.mock import patch
from asgiref.sync import async_to_sync
from django.contrib.auth import get_user_model
from django.core.exceptions import ValidationError
from django.test import Client, TestCase, TransactionTestCase, override_settings
from django.urls import reverse
from django.utils import timezone
from mcp.server.auth.provider import AccessToken
from mcp.server.mcpserver.exceptions import ToolError
from mcp_server.server import create_server, _docs_sync_result, _safe
from .documentation import (_fetch_snapshot, _git_env, _repository_url, audit_status,
document_diff, document_history, historical_document,
normal_path, sync_project)
from .models import DocumentationSync, Membership, ProjectDocument
from .services import create_project
from .templatetags.project_markdown import render_document_markdown
class DocumentationTests(TestCase):
def setUp(self):
users = get_user_model()
self.owner = users.objects.create_user('docs-owner', password='password')
self.viewer = users.objects.create_user('docs-viewer', password='password')
self.outsider = users.objects.create_user('docs-outsider', password='password')
self.project = create_project(self.owner, name='Documentation test',
git_repository_url='https://git.jorendegraaf.eu/owner/project.git')
Membership.objects.create(project=self.project, user=self.viewer, role='viewer')
def snapshot(self, path='docs/guide.md', markdown='# Guide\n\n[Next](next.md)\n', commit='a' * 40):
item = ProjectDocument(project=self.project, path=path, title='Guide', headings=['Guide'],
markdown=markdown, content_hash=hashlib.sha256(markdown.encode()).hexdigest(), source_commit=commit)
return (self.project.git_repository_url, 'refs/heads/main', commit, timezone.now(), [item], {})
def import_snapshot(self):
with patch('projects.documentation._fetch_snapshot', return_value=self.snapshot()):
return sync_project(self.owner, self.project)
def test_sync_replaces_deleted_documents_and_retains_last_good_on_error(self):
state = self.import_snapshot()
self.assertEqual(ProjectDocument.objects.filter(project=self.project).count(), 1)
self.assertEqual(state.indexed_commit, 'a' * 40)
DocumentationSync.objects.filter(project=self.project).update(last_attempt_at=timezone.now() - timedelta(minutes=2))
with patch('projects.documentation._fetch_snapshot', return_value=self.snapshot('README.md', '# New\n', 'b' * 40)):
sync_project(self.owner, self.project, force=True)
self.assertFalse(ProjectDocument.objects.filter(project=self.project, path='docs/guide.md').exists())
self.assertTrue(ProjectDocument.objects.filter(project=self.project, path='README.md').exists())
DocumentationSync.objects.filter(project=self.project).update(last_attempt_at=timezone.now() - timedelta(minutes=2))
from .documentation import DocumentationError
with patch('projects.documentation._fetch_snapshot', side_effect=DocumentationError('fetch unavailable')):
state = sync_project(self.owner, self.project, force=True)
self.assertEqual(state.indexed_commit, 'b' * 40)
self.assertIn('fetch unavailable', state.last_error)
self.assertTrue(ProjectDocument.objects.filter(project=self.project, path='README.md').exists())
def test_permissions_views_and_refresh(self):
self.import_snapshot()
home = reverse('projects:docs_home', args=[self.project.pk])
detail = reverse('projects:docs_document', args=[self.project.pk, 'docs/guide.md'])
refresh = reverse('projects:docs_refresh', args=[self.project.pk])
self.assertEqual(self.client.get(home).status_code, 302)
self.client.force_login(self.outsider)
self.assertEqual(self.client.get(home).status_code, 404)
self.assertEqual(self.client.get(detail).status_code, 404)
self.client.force_login(self.viewer)
self.assertContains(self.client.get(home), 'docs/guide.md')
self.assertContains(self.client.get(detail), 'Guide')
self.assertEqual(self.client.post(refresh).status_code, 403)
self.client.force_login(self.owner)
self.assertEqual(self.client.get(reverse('projects:docs_document', args=[self.project.pk, 'docs/../secret.md'])).status_code, 404)
csrf_client = Client(enforce_csrf_checks=True, HTTP_HOST='localhost')
csrf_client.force_login(self.owner)
self.assertEqual(csrf_client.post(refresh).status_code, 403)
csrf_client.get(home)
self.assertEqual(csrf_client.post(refresh, HTTP_X_CSRFTOKEN=csrf_client.cookies['csrftoken'].value).status_code, 302)
def test_markdown_links_and_untrusted_html(self):
html = str(render_document_markdown('# Guide\n\n[Next](next.md) [Missing](absent.md)\n\n<script>bad()</script>',
self.project.pk, 'docs/guide.md', {'docs/guide.md', 'docs/next.md'}))
self.assertIn(f'/projects/{self.project.pk}/docs/docs/next.md/', html)
self.assertIn('<h1 id="guide">Guide</h1>', html)
self.assertNotIn('href="absent.md"', html)
self.assertNotIn('<script>', html)
for path in ('../secret.md', '/etc/passwd', 'docs//file.md', 'docs\\file.md'):
with self.assertRaises(ValidationError):
normal_path(path)
def test_mcp_list_search_read_and_isolation(self):
self.import_snapshot()
ProjectDocument.objects.create(project=self.project, path='README.md', title='Read me',
markdown='# Read me\n', headings=['Read me'], content_hash=hashlib.sha256(b'# Read me\n').hexdigest(),
source_commit='a' * 40)
server = create_server()
token = AccessToken(token='test', client_id='test', scopes=['projects:read'], subject=str(self.viewer.pk))
with patch('mcp_server.server.get_access_token', return_value=token):
listed = async_to_sync(server.call_tool)('docs_list', {'project': str(self.project.pk), 'limit': 1}).structured_content
self.assertEqual(listed['items'][0]['path'], 'README.md')
following = async_to_sync(server.call_tool)('docs_list', {'project': str(self.project.pk), 'limit': 1, 'cursor': listed['next_cursor']}).structured_content
self.assertEqual(following['items'][0]['path'], 'docs/guide.md')
found = async_to_sync(server.call_tool)('docs_search', {'query': 'Guide'}).structured_content
self.assertEqual(found['total'], 1)
self.assertNotIn('markdown', found['items'][0])
read = async_to_sync(server.call_tool)('docs_read', {'project': str(self.project.pk), 'path': 'docs/guide.md', 'start_line': 1, 'end_line': 1}).structured_content
self.assertEqual(read['markdown'], '# Guide\n')
self.assertTrue(read['truncated'])
with self.assertRaises(ToolError):
async_to_sync(server.call_tool)('docs_list', {'project': str(self.project.pk), 'cursor': 'stale:1'})
with self.assertRaises(ToolError):
async_to_sync(server.call_tool)('docs_read', {'project': str(self.project.pk), 'path': '../secret.md'})
denied = AccessToken(token='test', client_id='test', scopes=['projects:read'], subject=str(self.outsider.pk))
with patch('mcp_server.server.get_access_token', return_value=denied):
self.assertEqual(async_to_sync(server.call_tool)('docs_search', {'query': 'Guide'}).structured_content['total'], 0)
with self.assertRaises(ToolError):
async_to_sync(server.call_tool)('docs_read', {'project': str(self.project.pk), 'path': 'docs/guide.md'})
def test_url_allowlist_and_per_project_credentials(self):
valid_url = self.project.git_repository_url
self.assertEqual(_repository_url(self.project), valid_url)
for url in ('http://git.jorendegraaf.eu/x', 'https://evil.example/x',
'https://user:secret@git.jorendegraaf.eu/x', 'https://git.jorendegraaf.eu/a/../b'):
self.project.git_repository_url = url
from .documentation import DocumentationError
with self.assertRaises(DocumentationError):
_repository_url(self.project)
self.project.git_repository_url = 'https://user:secret@git.jorendegraaf.eu/x'
with self.assertRaises(ValidationError):
self.project.full_clean()
self.project.git_repository_url = valid_url
credentials = {str(self.project.pk): {'repository_url': valid_url,
'username': 'readonly', 'token': 'secret-token'}}
with override_settings(PROJECT_DOCS_CREDENTIALS_JSON=json.dumps(credentials)):
env = _git_env(self.project)
self.assertIn('Authorization: Basic ', env['GIT_CONFIG_VALUE_0'])
other = create_project(self.owner, name='Other')
self.assertNotIn('GIT_CONFIG_VALUE_0', _git_env(other))
def test_invalid_audit_state_and_concurrent_claim(self):
state = self.import_snapshot()
self.assertEqual(audit_status(state), 'Unknown / due')
state.audit_state = {'last_successful_audit': 'broken', 'last_audited_commit': 'a' * 40}
self.assertEqual(audit_status(state), 'Unknown / due')
DocumentationSync.objects.filter(pk=state.pk).update(
sync_token='held', sync_started_at=timezone.now(), last_attempt_at=timezone.now() - timedelta(hours=1))
with patch('projects.documentation._fetch_snapshot') as fetch:
sync_project(self.owner, self.project)
fetch.assert_not_called()
def test_symlink_document_is_not_indexed(self):
blob = 'b' * 40
listing = f'120000 blob {blob}\tdocs/link.md\0'.encode() + f'100644 blob {blob}\tdocs/real.md\0'.encode()
outputs = [f'ref: refs/heads/main\tHEAD\n{"a" * 40}\tHEAD\n'.encode(), b'',
('a' * 40 + '\n').encode(), b'2026-10-20T12:00:00+00:00\n', listing, b'# Real\n']
with tempfile.TemporaryDirectory() as root, override_settings(PROJECT_DOCS_MIRROR_ROOT=root):
(Path(root) / str(self.project.pk)).mkdir()
with patch('projects.documentation._git', side_effect=outputs) as git_call:
_, _, _, _, docs, _ = _fetch_snapshot(self.project)
self.assertEqual([item.path for item in docs], ['docs/real.md'])
self.assertEqual(sum(1 for call in git_call.call_args_list if 'cat-file' in call.args[0]), 1)
def test_retained_git_history_and_diff_are_scoped(self):
def git(*args, cwd=None):
return subprocess.check_output(['git', *args], cwd=cwd, stderr=subprocess.DEVNULL).decode().strip()
with tempfile.TemporaryDirectory() as root, override_settings(PROJECT_DOCS_MIRROR_ROOT=Path(root) / 'mirrors'):
work = Path(root) / 'work'
work.mkdir()
git('init', '-q', cwd=work)
git('config', 'user.name', 'Test', cwd=work)
git('config', 'user.email', 'test@example.com', cwd=work)
(work / 'docs').mkdir()
path = work / 'docs' / 'guide.md'
path.write_text('# Old\n')
git('add', '.', cwd=work)
git('commit', '-qm', 'first', cwd=work)
first = git('rev-parse', 'HEAD', cwd=work)
path.write_text('# New\n')
git('commit', '-qam', 'second', cwd=work)
second = git('rev-parse', 'HEAD', cwd=work)
mirror = Path(root) / 'mirrors' / str(self.project.pk)
mirror.parent.mkdir()
git('clone', '--bare', '-q', str(work), str(mirror))
DocumentationSync.objects.create(project=self.project, indexed_commit=second,
indexed_repository_url=self.project.git_repository_url)
ProjectDocument.objects.create(project=self.project, path='docs/guide.md', title='New',
markdown='# New\n', headings=['New'], content_hash=hashlib.sha256(b'# New\n').hexdigest(),
source_commit=second)
history = document_history(self.viewer, self.project, 'docs/guide.md')
self.assertEqual([item['commit'] for item in history], [second, first])
old = historical_document(self.viewer, self.project, 'docs/guide.md', first)
self.assertEqual(old.markdown, '# Old\n')
diff, truncated = document_diff(self.viewer, self.project, 'docs/guide.md', first, second)
self.assertIn('-# Old', diff)
self.assertIn('+# New', diff)
self.assertFalse(truncated)
from django.http import Http404
with self.assertRaises(Http404):
document_history(self.outsider, self.project, 'docs/guide.md')
def test_project_delete_cleans_private_mirror_after_commit(self):
with tempfile.TemporaryDirectory() as root, override_settings(PROJECT_DOCS_MIRROR_ROOT=root):
mirror = Path(root) / str(self.project.pk)
mirror.mkdir()
(mirror / 'marker').write_text('private')
with self.captureOnCommitCallbacks(execute=True):
self.project.delete()
self.assertFalse(mirror.exists())
class DocumentationMcpSyncTests(TransactionTestCase):
"""Exercise the sync handler without the in-process MCP async bridge."""
def setUp(self):
users = get_user_model()
self.owner = users.objects.create_user('sync-owner', password='password')
self.viewer = users.objects.create_user('sync-viewer', password='password')
self.project = create_project(self.owner, name='MCP sync test',
git_repository_url='https://git.jorendegraaf.eu/owner/project.git')
Membership.objects.create(project=self.project, user=self.viewer, role='viewer')
def snapshot(self):
markdown = '# Read me\n'
document = ProjectDocument(project=self.project, path='docs/README.md', title='Read me',
headings=['Read me'], markdown=markdown, content_hash=hashlib.sha256(markdown.encode()).hexdigest(),
source_commit='a' * 40)
return (self.project.git_repository_url, 'refs/heads/main', 'a' * 40, timezone.now(), [document], {})
def test_mcp_sync_permissions_metadata_cooldown_and_failure(self):
server = create_server()
def call(arguments):
return _safe(lambda: _docs_sync_result(**arguments))
self.assertIn('docs_sync', [tool.name for tool in server._tool_manager.list_tools()])
owner = AccessToken(token='test', client_id='test', scopes=['projects:read', 'projects:write'], subject=str(self.owner.pk))
read_only = AccessToken(token='test', client_id='test', scopes=['projects:read'], subject=str(self.owner.pk))
viewer = AccessToken(token='test', client_id='test', scopes=['projects:read', 'projects:write'], subject=str(self.viewer.pk))
args = {'project': str(self.project.pk)}
with patch('mcp_server.server.get_access_token', return_value=read_only):
with self.assertRaisesRegex(ToolError, 'projects:write authorization required'):
call(args)
with patch('mcp_server.server.get_access_token', return_value=viewer):
with self.assertRaisesRegex(ToolError, 'not_found|permission_denied'):
call(args)
with patch('mcp_server.server.get_access_token', return_value=owner):
with patch('projects.documentation._fetch_snapshot', return_value=self.snapshot()) as fetch:
first = call(args)
self.assertEqual(first['status'], 'completed')
self.assertEqual(first['document_count'], 1)
self.assertEqual(first['indexed_commit'], 'a' * 40)
self.assertIsNotNone(first['last_success_at'])
again = call(args)
self.assertEqual(again['status'], 'already_current')
self.assertIsNotNone(again['retry_after_seconds'])
diverged = call({**args, 'expected_remote_commit': 'b' * 40})
self.assertEqual(diverged['status'], 'failed')
self.assertIn('differs', diverged['error'])
fetch.assert_called_once()
DocumentationSync.objects.filter(project=self.project).update(last_attempt_at=timezone.now() - timedelta(minutes=2))
from .documentation import DocumentationError
with patch('projects.documentation._fetch_snapshot', side_effect=DocumentationError('fetch unavailable')):
failed = call(args)
self.assertEqual(failed['status'], 'failed')
self.assertEqual(failed['indexed_commit'], 'a' * 40)
self.assertIn('fetch unavailable', failed['error'])
self.assertTrue(ProjectDocument.objects.filter(project=self.project, path='docs/README.md').exists())