271 lines
17 KiB
Python
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())
|