service

service 모듈은 JSH 애플리케이션에서 service controller의 JSON-RPC API를 호출할 수 있도록 해주는 클라이언트 모듈입니다.

일반적으로 아래처럼 사용합니다.

const service = require('service');

service controller 주소는 보통 shell/session이 설정한 SERVICE_CONTROLLER 환경 변수에서 가져옵니다.

controller는 실행할 때마다 random 주소로 열릴 수 있으므로 일반적으로는 주소를 하드코딩하지 않습니다. 별도의 controller 주소를 이미 알고 있거나 명시적으로 다른 controller에 연결해야 하는 경우에만 options.controller를 사용합니다.

Client

Client는 service controller와 통신하는 기본 클라이언트 타입입니다.

재사용할 클라이언트 인스턴스가 필요하면 new service.Client(...) 형태를 기본으로 사용하는 것이 좋습니다.

사용 형식

new Client([options])

옵션

controller는 고정된 기본 주소를 갖지 않습니다. SERVICE_CONTROLLER가 없고 options.controller도 지정하지 않으면 클라이언트 생성은 실패합니다.

사용 예시

1
2

const service = require('service');
const client = new service.Client({ timeout: 1000 });

위 예시는 SERVICE_CONTROLLER 환경 변수가 이미 설정되어 있다고 가정합니다.

명시적으로 다른 controller 주소를 사용할 때만 아래처럼 controller를 지정합니다.

1
2
3
4
5

const service = require('service');
const client = new service.Client({
    controller: 'unix:///tmp/example-service-controller.sock',
    timeout: 1000,
});

주요 프로퍼티

• controller
• timeout
• runtime
• details

Client 메서드

• call(method[, params], callback)
• status([name], callback)
• read(callback)
• update(callback)
• reload(callback)
• install(config, callback)
• uninstall(name, callback)
• start(name, callback)
• stop(name, callback)

사용 예시

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

const service = require('service');
const client = new service.Client();

client.status((err, services) => {
    if (err) {
        console.println(err.message);
        return;
    }
    console.println('count=', services.length);
});

call()

임의의 service controller RPC 메서드를 직접 호출합니다.

사용 형식

client.call(method[, params], callback)

사용 예시

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

const service = require('service');
const client = new service.Client();

client.call('service.list', null, (err, result) => {
    if (err) {
        console.println(err.message);
        return;
    }
    console.println(result.length);
});

status()

현재 서비스 상태를 조회합니다.

• name을 생략하면 서비스 목록 snapshot을 반환합니다.
• name을 지정하면 단일 서비스 snapshot을 반환합니다.
• 이 메서드는 servicectl status [service_name] 명령 형태에 맞춰져 있습니다.

사용 형식

client.status([name], callback)

사용 예시

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18

const service = require('service');
const client = new service.Client();

client.status((err, services) => {
    if (err) {
        console.println(err.message);
        return;
    }
    console.println('count=', services.length);
});

client.status('alpha', (err, snapshot) => {
    if (err) {
        console.println(err.message);
        return;
    }
    console.println(snapshot.status);
});

read()

service config directory를 다시 읽고 최신 reread snapshot을 반환합니다.

사용 형식

client.read(callback)

update()

현재 reread snapshot을 적용하고 update 결과를 반환합니다.

• update()는 현재 reread 결과에 포함된 차이만 적용합니다.
• reread 결과에 영향을 받은 서비스만 stop, start, add, remove 합니다.

사용 형식

client.update(callback)

reload()

config를 다시 읽고 그 결과를 바로 적용합니다.

• reload()는 update()와 달리 현재 실행 중인 서비스를 먼저 모두 종료합니다.
• 그 다음 현재 config에서 enable 된 서비스만 다시 시작합니다.
• 따라서 reload() 이전에 실행 중이던 서비스라도 현재 config에서 enable 되어 있지 않으면 다시 시작되지 않습니다.

사용 형식

client.reload(callback)

install()

config object로 서비스를 설치하고 설치된 service snapshot을 반환합니다.

사용 형식

client.install(config, callback)

사용 예시

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

const service = require('service');
const client = new service.Client();

client.install({
    name: 'alpha',
    enable: false,
    executable: 'echo',
    args: ['hello'],
}, (err, snapshot) => {
    if (err) {
        console.println(err.message);
        return;
    }
    console.println(snapshot.config.name, snapshot.status);
});

uninstall()

서비스를 제거하고 성공 시 true를 반환합니다.

사용 형식

client.uninstall(name, callback)

start()

서비스를 시작하고 갱신된 service snapshot을 반환합니다.

사용 형식

client.start(name, callback)

stop()

서비스를 중지하고 갱신된 service snapshot을 반환합니다.

사용 형식

client.stop(name, callback)

runtime.get()

서비스의 runtime snapshot을 조회합니다.

• 반환값에는 output과 details가 포함됩니다.

사용 형식

client.runtime.get(name, callback)

사용 예시

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

const service = require('service');
const client = new service.Client();

client.runtime.get('alpha', (err, runtime) => {
    if (err) {
        console.println(err.message);
        return;
    }
    console.println(JSON.stringify(runtime.details || {}));
});

details.get()

서비스 detail 값을 조회합니다.

• key를 생략하면 전체 details snapshot을 반환합니다.
• key를 지정하면 해당 key가 없을 때 오류를 반환합니다.

사용 형식

client.details.get(name[, key], callback)

사용 예시

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

const service = require('service');
const client = new service.Client();

client.details.get('alpha', 'health', (err, runtime) => {
    if (err) {
        console.println(err.message);
        return;
    }
    console.println(runtime.details.health);
});

details.add()

새 detail key/value를 추가합니다.

• 동일한 key가 이미 존재하면 오류를 반환합니다.

사용 형식

client.details.add(name, key, value, callback)

details.update()

기존 detail key/value를 갱신합니다.

• key가 존재하지 않으면 오류를 반환합니다.

사용 형식

client.details.update(name, key, value, callback)

details.set()

detail key/value를 설정합니다.

• key가 없으면 새로 생성하고, 있으면 덮어씁니다.

사용 형식

client.details.set(name, key, value, callback)

사용 예시

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

const service = require('service');
const client = new service.Client();

client.details.set('alpha', 'health', 'ok', (err, runtime) => {
    if (err) {
        console.println(err.message);
        return;
    }
    console.println(runtime.details.health);
});

details.delete()

detail key를 제거합니다.

• key가 없으면 오류를 반환합니다.

사용 형식

client.details.delete(name, key, callback)

resolveController()

controller 주소를 결정합니다.

• 인자를 넘기면 그 값을 사용합니다.
• 인자가 없으면 SERVICE_CONTROLLER 환경 변수를 조회합니다.

사용 형식

resolveController([value])

동작 예시

1
2
3

const service = require('service');
console.println(service.resolveController());
console.println(service.resolveController('unix:///tmp/example-service-controller.sock'));

동작 참고

• 모든 API는 callback 기반 비동기 스타일입니다.
• controller 연결 실패, timeout, RPC 오류는 callback의 첫 번째 인자로 전달됩니다.
• service RPC가 진행 중인 동안에는 짧은 top-level script가 callback 전에 종료되지 않도록 module이 내부적으로 request lifetime을 유지합니다.
• 이 keepalive 구간은 실제 timeout 값에 맞춰 동작하고, 요청이 성공, 실패, timeout 중 하나로 정리되면 바로 해제됩니다.
• new Client()는 options.controller를 생략하면 SERVICE_CONTROLLER를 기본으로 사용합니다.