resource

README

dsa-resource-spec

課題定義 resource.yaml を検証・読み込みする Go ライブラリと CLI。

やりたいこと	読む文書
課題の定義を書く	Resource 仕様
課題を登録してイメージをビルドする	登録・ビルド手順
Backend・Judge を実装する	実行規則
設計の理由を知る	設計

開発環境

• Go 1.27

Goの環境はNix, direnvで設定することも可。

direnv allow .
check

CLI

# manifest.yaml と登録された全課題を検証する
go run ./cmd/resource-spec validate <manifest-dir>
# マニフェストと登録された全課題のメタデータを JSON 出力する
go run ./cmd/resource-spec catalog <manifest-dir>
# 指定した課題の解決済み JSON を出力する
go run ./cmd/resource-spec show <manifest-dir> <resource-id>

GitHub Actions 用の検証・公開処理は、別CLIの resource-ci に分離している。使い方は 公開手順 を参照。

Go から使う

manifest, err := resource.LoadManifest("path/to/manifest-directory")
if err != nil {
    return err
}
// Resources は manifest.yaml の登録順。ID は Metadata.ID にある。
data, err := json.Marshal(manifest.Resources[0])
if err != nil {
    return err
}
restored, err := resource.DecodeResource(bytes.NewReader(data))

関数	用途
LoadManifest(dir string) (*Manifest, error)	manifest.yaml と全課題を検証し、素材の読み込み・単位変換・既定値の補完を行う。
Resource.Hash() (string, error)	呼び出し時点の Resource の JSON から SHA-256 を計算する。
DecodeResource(r io.Reader) (*Resource, error)	解決済み Resource の JSON を復元し、依存関係・実行制限などを検証する。未知フィールドと複数文書は拒否する。

Documentation

Overview

Package resource loads author manifests and validates self-contained resources.

Index

• type ArtifactInput
• type ArtifactOutput
• type Artifacts
• type Expected
• type ImageBuild
• type Job
• type Limits
• type Manifest
  • func LoadManifest(dir string) (*Manifest, error)
• type MatchMode
• type Metadata
• type OutputExpectation
• type Preset
• type Resource
  • func DecodeResource(r io.Reader) (*Resource, error)
  • func (r Resource) Hash() (string, error)
• type Step
• type Workflow

Types

type ArtifactInput

type ArtifactInput struct {
	FromJob string `json:"from-job"`
	Name    string `json:"name"`
	Path    string `json:"path"`
}

type ArtifactOutput

type ArtifactOutput struct {
	Name        string `json:"name"`
	Path        string `json:"path"`
	Visibility  string `json:"visibility"`
	ContentType string `json:"content-type"`
}

type Artifacts

type Artifacts struct {
	Inputs  []ArtifactInput  `json:"inputs"`
	Outputs []ArtifactOutput `json:"outputs"`
}

type Expected

type Expected struct {
	ExitCode *int               `json:"exit-code"` // nil means the exit code is not checked.
	Stdout   *OutputExpectation `json:"stdout"`
	Stderr   *OutputExpectation `json:"stderr"`
}

type ImageBuild

type ImageBuild struct {
	Context    string   `json:"context"`
	Dockerfile string   `json:"dockerfile"`
	Image      string   `json:"image"`
	Platforms  []string `json:"platforms"`
}

ImageBuild holds CI settings; build files are not read by this package.

type Job

type Job struct {
	Name         string     `json:"name"`
	Visibility   string     `json:"visibility"`
	Depends      []string   `json:"depends"`
	SandboxImage string     `json:"sandbox-image"`
	Limits       Limits     `json:"limits"`
	Artifacts    *Artifacts `json:"artifacts"`
	Steps        []Step     `json:"steps"`
}

type Limits

type Limits struct {
	CPU           int   `json:"cpu"`
	Memory        int64 `json:"memory"`
	PIDs          int   `json:"pids"`
	StdoutSize    int64 `json:"stdout-size"`
	StderrSize    int64 `json:"stderr-size"`
	WorkspaceSize int64 `json:"workspace-size"`
	ArtifactSize  int64 `json:"artifact-size"`
}

type Manifest

type Manifest struct {
	Resources     []Resource            `json:"resources"`
	SandboxImages map[string]ImageBuild `json:"sandbox-images"`
}

Manifest contains resolved resources in registration order and CI image build settings.

func LoadManifest

func LoadManifest(dir string) (*Manifest, error)

LoadManifest validates manifest.yaml and resolves every registered resource. The caller must keep the input directory stable throughout the call.

type MatchMode

type MatchMode string

MatchMode selects the output comparison rule.

const (
	MatchExact  MatchMode = "exact"
	MatchEasy   MatchMode = "easy"
	MatchSorted MatchMode = "sorted"
)

type Metadata

type Metadata struct {
	ID      string `json:"id"`
	Name    string `json:"name"`
	Version string `json:"version"`
}

type OutputExpectation

type OutputExpectation struct {
	Content []byte    `json:"content"`
	Match   MatchMode `json:"match"`
}

type Preset

type Preset struct {
	Content    []byte `json:"content"`
	Executable bool   `json:"executable"`
	Path       string `json:"path"`
}

type Resource

type Resource struct {
	Metadata  Metadata            `json:"metadata"`
	Workflows map[string]Workflow `json:"workflows"`
}

Resource contains resolved data and retains neither source paths nor file handles. Marshal it with encoding/json to save or distribute it.

func DecodeResource

func DecodeResource(r io.Reader) (*Resource, error)

DecodeResource restores one resolved JSON resource, rejecting unknown fields and invalid runtime data. It does not read files or apply authoring defaults.

func (Resource) Hash

func (r Resource) Hash() (string, error)

Hash returns the SHA-256 of the Resource's current JSON encoding.

type Step

type Step struct {
	Name     string        `json:"name"`
	Compile  bool          `json:"compile"`
	Run      string        `json:"run"`
	Stdin    []byte        `json:"stdin"`
	Timeout  time.Duration `json:"timeout"`
	Expected Expected      `json:"expected"`
}

type Workflow

type Workflow struct {
	Name        string         `json:"name"`
	Description string         `json:"description"`
	Presets     []Preset       `json:"presets"`
	Jobs        map[string]Job `json:"jobs"`
}