Kod Çalıştırma Motoru (Code Execution Engine)

Achidemy, interaktif kodlama egzersizleri için Piston API tabanlı bir kod çalıştırma motoru kullanır. Öğrenciler kod yazar, test eder ve gerçek zamanlı geri bildirim alır. Bu sayfa kod çalıştırma altyapısını, coding exercises veritabanı şemasını ve GraphQL mutation’larını açıklar.

Code Engine

Dosya: app/lib/code-engine.ts

Piston API Entegrasyonu

Endpoint: https://emkc.org/api/v2/piston/execute

Desteklenen Diller:

• JavaScript, Python, Java, C++, C#, Go, Rust, TypeScript, PHP, Ruby, Swift, Kotlin, vb.

Fonksiyon: executeCode

executeCode(
  language: string,
  code: string,
  input: string = "",
  options?: { runTimeout?: number; compileTimeout?: number }
): Promise<ExecutionResult>

Parametreler:

Parametre	Tip	Açıklama
language	string	Dil kodu (örn: javascript, python, java)
code	string	Çalıştırılacak kod
input	string	stdin input (opsiyonel)
options.runTimeout	number	Çalıştırma timeout (ms, varsayılan: 10000)
options.compileTimeout	number	Derleme timeout (ms, varsayılan: 15000)

Dönüş Değeri: ExecutionResult

interface ExecutionResult {
  success: boolean;
  stdout: string | null;
  stderr: string | null;
  output: string | null;
  error: string | null;
  exitCode: number | null;
  signal: string | null;
}

Güvenlik

• Sandbox: Piston API her kod çalıştırmayı izole bir sandbox’ta yürütür
• Timeout: Çalıştırma ve derleme için timeout limitleri
• Resource Limits: CPU ve memory limitleri Piston tarafından uygulanır

---

Coding Exercises Veritabanı Şeması

Dosya: app/db/schema.ts

1. Coding Exercises Tablosu

Tablo: coding_exercises

Alan	Tip	Açıklama
id	uuid	Primary key
section_id	uuid (FK → sections)	Hangi bölüme ait
title	text	Egzersiz başlığı
description	text	Açıklama (markdown desteklenir)
language	text	Programlama dili (javascript, python, vb.)
initial_code	text	Öğrenciye verilen başlangıç kodu
solution_code	text	Çözüm kodu (eğitmen için)
hints	text	İpuçları (opsiyonel)
order	integer	Bölüm içindeki sıra

2. Test Cases Tablosu

Tablo: coding_exercise_test_cases

Alan	Tip	Açıklama
id	uuid	Primary key
exercise_id	uuid (FK → coding_exercises)	Hangi egzersize ait
input	text	Test input’u (öğrenci kodunun sonuna eklenecek çağrı kodu)
expected_output	text	Beklenen çıktı
description	text	Test açıklaması (örn: “Boş array için”)
hint	text	Test geçemediğinde öğrenciye verilecek özel ipucu
is_hidden	boolean	Gizli test mi? (öğrenci göremez, sadece geçti/geçmedi görür)
order	integer	Test sırası

Örnek Test Case:

• input: console.log(sum(5, 10))
• expected_output: 15
• hint: “Toplama fonksiyonunuzun parametreleri doğru mu?“

3. User Exercise Submissions Tablosu

Tablo: user_exercise_submissions

Alan	Tip	Açıklama
id	uuid	Primary key
user_id	text (FK → users)	Öğrenci ID
exercise_id	uuid (FK → coding_exercises)	Hangi egzersiz
submitted_code	text	Öğrencinin gönderdiği kod
passed	boolean	Tüm testler geçti mi?
passed_tests	integer	Geçen test sayısı
total_tests	integer	Toplam test sayısı
execution_time	integer	Çalıştırma süresi (ms)
submitted_at	timestamp	Gönderim zamanı

---

GraphQL Mutation: submitExercise

Dosya: app/graphql/schema.ts

Mutation Tanımı

mutation SubmitExercise($exerciseId: ID!, $code: String!) {
  submitExercise(exerciseId: $exerciseId, code: $code) {
    passed
    passedTests
    totalTests
    executionTime
    testResults {
      testCaseId
      input
      expected
      actual
      passed
      error
      hint
    }
  }
}

Çalışma Akışı

1. Egzersiz ve test case’leri çek: exerciseId ile coding_exercises ve coding_exercise_test_cases sorgulanır
2. Her test case için kod çalıştır:
   • input değeri öğrenci kodunun sonuna eklenir (örn: code + "\n" + testCase.input)
   • executeCode(exercise.language, fullCode) çağrılır
   • stdout ile expected_output karşılaştırılır
3. Sonuçları kaydet: user_exercise_submissions tablosuna kayıt
4. Test sonuçlarını döndür: Her test için passed, actual, error, hint bilgileri

Test Sonuç Formatı

interface TestCaseResult {
  testCaseId: string;
  input: string | null;
  expected: string;
  actual: string;
  passed: boolean;
  error: string | null;
  hint: string | null;  // Test geçmediyse ve hint varsa
}

---

Frontend: CodingWorkspace Component

Dosya: app/components/learn/CodingWorkspace.tsx

Özellikler

• Monaco Editor: Kod editörü (VS Code editörü)
• Test Çalıştırma: “Run” butonu ile kod çalıştırma
• Test Sonuçları: Her test için geçti/geçmedi, çıktı, hata mesajı gösterimi
• Hint Gösterimi: Test geçmediğinde ipucu gösterimi
• Otomatik Kaydetme: Kod değişiklikleri localStorage’a kaydedilir
• Tamamlanma Durumu: Tüm testler geçtiğinde egzersiz tamamlanır

Kullanım

<CodingWorkspace
  exercise={exercise}
  courseId={courseId}
  initialCompleted={false}
  onComplete={() => {/* egzersiz tamamlandı */}}
  onNext={() => {/* sonraki egzersize geç */}}
/>

---

Eğitmen: Test Case Yönetimi

Dosya: app/components/instructor/TestCaseManager.tsx

Eğitmenler coding exercise oluştururken test case’leri ekleyebilir:

• Public Test Cases: Öğrenci görebilir (açık testler)
• Hidden Test Cases: Öğrenci göremez, sadece geçti/geçmedi görür (gizli testler)
• Hint Ekleme: Her test case için özel ipucu eklenebilir
• Input/Output: Test input’u ve beklenen çıktı tanımlanır

---

Güvenlik ve Limitler

Timeout Limitleri

İşlem	Varsayılan	Maksimum
Çalıştırma	10 saniye	30 saniye
Derleme	15 saniye	30 saniye

Rate Limiting

• Piston API rate limit’leri uygulanır
• Aynı anda çok fazla istek gönderilmemelidir

Kod İçeriği Kontrolü

• Moderation: Gönderilen kod içeriği moderation.ts ile kontrol edilebilir (gelecekte)
• Malicious Code: Piston sandbox içinde çalıştığı için sistem güvenliği korunur

---

İlgili Dosyalar

• app/lib/code-engine.ts — Piston API entegrasyonu
• app/graphql/schema.ts — submitExercise mutation
• app/components/learn/CodingWorkspace.tsx — Öğrenci kod editörü
• app/components/instructor/TestCaseManager.tsx — Test case yönetimi
• app/db/schema.ts — Veritabanı şeması (coding_exercises, coding_exercise_test_cases, user_exercise_submissions)