resource

README

dsa-resource-spec

課題定義 resource.yaml の検証・読み込みと出力比較を提供する Go ライブラリと CLI。

やりたいこと	読む文書
課題の定義を書く	リソース仕様
課題を登録してイメージをビルドする	登録・ビルド手順
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 に分離している。使い方は 公開手順 を参照。

CLI のリリース

CLI Release workflow をデフォルトブランチに追加後、 Actions の CLI Release → Run workflow で、push 済みのタグ（例: v1.1.0）を指定する。 指定タグのソースを検証・ビルドして GitHub Release を作成する。既存タグの付け替えは不要。 タグは vMAJOR.MINOR.PATCH 形式に対応し、既存 Release の上書きは行わない。

Linux / macOS の amd64 / arm64 向けに、resource-spec・resource-ci・LICENSE をまとめた resource-cli-<tag>-<os>-<arch>.tar.gz と checksums.txt を配布する。 利用側はバージョンを固定してダウンロードし、チェックサムを照合して展開した CLI を使う。 CLI の実行に Go は不要だが、課題公開には引き続き Git・Docker Buildx・regctl が必要。 課題 JSON の release/ への公開とは別の処理である。

Go から使う

import resource "github.com/dsa-uts/dsa-resource-spec"

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 を復元し、依存関係・実行制限などを検証する。未知フィールドと複数文書は拒否する。
MatchOutput(actual, expected []byte, mode MatchMode) (bool, error)	MatchExact・MatchEasy・MatchSorted で出力を比較する。未知・空のモードはエラー。不一致と不正な UTF-8 は false, nil。

if want := step.Expected.Stdout; want != nil {
    matched, err := resource.MatchOutput(stdout, want.Content, want.Match)
    // err は設定エラー、matched は比較結果として扱う。
}

期待値が省略されている場合は呼び出し側で比較を省く。 詳しい比較規則は 出力の比較 を参照。

Documentation

Overview

Package resource loads author manifests, validates self-contained resources, and compares UTF-8 output against expectations.

Index

• func MatchOutput(actual, expected []byte, mode MatchMode) (bool, error)
• 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 RuntimePath
  • func (p RuntimePath) Validate() error
• type SandboxImage
  • func (s SandboxImage) Validate() error
• type Step
• type Version
  • func (v Version) Validate() error
• type Workflow

Functions

func MatchOutput

func MatchOutput(actual, expected []byte, mode MatchMode) (bool, error)

MatchOutput compares UTF-8 output using the given mode without modifying inputs. Exact compares bytes; easy compares whitespace-separated tokens on each line; sorted additionally ignores token order within each line, preserving duplicates. Easy and sorted recognize LF, CRLF and CR, and remove exactly one final newline. Nil slices are empty output. Invalid UTF-8 in either input is a mismatch, even in exact mode. An unknown mode (including the empty string) returns an error.

Types

type ArtifactInput

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

type ArtifactOutput

type ArtifactOutput struct {
	Name        string      `json:"name" validate:"identifier"`
	Path        RuntimePath `json:"path" validate:"validateFn"`
	Visibility  string      `json:"visibility" validate:"oneof=public private"`
	ContentType string      `` /* 156-byte string literal not displayed */
}

type Artifacts

type Artifacts struct {
	Inputs  []ArtifactInput  `json:"inputs" validate:"unique=Path,dive"`
	Outputs []ArtifactOutput `json:"outputs" validate:"unique=Name,unique=Path,dive"`
}

type Expected

type Expected struct {
	ExitCode *int               `json:"exit-code" validate:"omitnil,gte=0,lte=255"` // nil means the exit code is not checked.
	Stdout   *OutputExpectation `json:"stdout" validate:"omitnil"`
	Stderr   *OutputExpectation `json:"stderr" validate:"omitnil"`
}

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" validate:"oneof=public private"`
	Depends      []string     `json:"depends" validate:"unique"`
	SandboxImage SandboxImage `json:"sandbox-image" validate:"validateFn"`
	Limits       Limits       `json:"limits"`
	Artifacts    *Artifacts   `json:"artifacts" validate:"omitnil"`
	Steps        []Step       `json:"steps" validate:"min=1,dive"`
}

type Limits

type Limits struct {
	CPU           int   `json:"cpu" validate:"gte=1,lte=2"`
	Memory        int64 `json:"memory" validate:"gt=0,lte=536870912"`
	PIDs          int   `json:"pids" validate:"gte=1,lte=256"`
	StdoutSize    int64 `json:"stdout-size" validate:"gt=0,lte=32768"`
	StderrSize    int64 `json:"stderr-size" validate:"gt=0,lte=32768"`
	WorkspaceSize int64 `json:"workspace-size" validate:"gt=0,lte=134217728"`
	ArtifactSize  int64 `json:"artifact-size" validate:"gt=0,lte=1048576"`
}

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" validate:"identifier"`
	Name    string  `json:"name" validate:"required"`
	Version Version `json:"version" validate:"validateFn"`
}

type OutputExpectation

type OutputExpectation struct {
	Content []byte    `json:"content"`
	Match   MatchMode `json:"match" validate:"oneof=exact easy sorted"`
}

type Preset

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

type Resource

type Resource struct {
	Metadata      Metadata            `json:"metadata"`
	RequiredFiles []string            `json:"required-files" validate:"dive,notblank"`
	Workflows     map[string]Workflow `json:"workflows" validate:"min=1,dive,keys,identifier,endkeys"`
}

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. Missing or null required-files is restored as an empty array.

func (Resource) Hash

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

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

type RuntimePath

type RuntimePath string

RuntimePath is a POSIX relative path, independent of the local filesystem.

func (RuntimePath) Validate

func (p RuntimePath) Validate() error

type SandboxImage

type SandboxImage string

SandboxImage is a fully qualified container image with a tag or digest.

func (SandboxImage) Validate

func (s SandboxImage) Validate() error

type Step

type Step struct {
	Name     string        `json:"name"`
	Compile  bool          `json:"compile"`
	Run      string        `json:"run" validate:"notblank,excludesall=\x00"`
	Stdin    []byte        `json:"stdin"`
	Timeout  time.Duration `json:"timeout" validate:"gt=0"`
	Expected Expected      `json:"expected"`
}

type Version

type Version string

Version is a v-prefixed semantic version with all three numeric components.

func (Version) Validate

func (v Version) Validate() error

type Workflow

type Workflow struct {
	Name        string         `json:"name"`
	Description string         `json:"description"`
	Presets     []Preset       `json:"presets" validate:"unique=Path,dive"`
	Jobs        map[string]Job `json:"jobs" validate:"min=1,dive,keys,identifier,endkeys"`
}