resource

package module
v1.7.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Oct 10, 2026 License: MIT Imports: 22 Imported by: 0

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 MatchExact・MatchEasy・MatchSorted で出力を比較する。不一致と未知・空のモードは false。UTF-8 の妥当性は検証しない。 
if want := step.Expected.Stdout; want != nil {
    matched := resource.MatchOutput(stdout, want.Content, want.Match)
    // matched を比較結果として扱う。
}

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

Documentation

Overview

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

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func MatchOutput added in v1.1.0 

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

MatchOutput compares 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. Invalid UTF-8 bytes are preserved and compared. An unknown mode (including the empty string) returns false.

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"`
	Description string  `json:"description" validate:"max=64"`
	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 added in v1.5.0 

type RuntimePath string

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

func (RuntimePath) Validate added in v1.5.0 

func (p RuntimePath) Validate() error

type SandboxImage added in v1.5.0 

type SandboxImage string

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

func (SandboxImage) Validate added in v1.5.0 

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 added in v1.5.0 

type Version string

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

func (Version) Validate added in v1.5.0 

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"`
}

Source Files

View all Source files

Directories

Path Synopsis
cmd
resource-ci command
resource-ci runs this repository's GitHub validation and publication tasks.
 resource-ci runs this repository's GitHub validation and publication tasks.
resource-spec command
internal
publishing
Package publishing implements this repository's GitHub publication workflow.
 Package publishing implements this repository's GitHub publication workflow.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.